chore: Updated security workflow readme

README.md

@@ -1,19 +1,21 @@
 # Droid Actions for GitHub
 
-This GitHub Action powers the Factory **Droid** app. It watches your pull requests for the two supported commands and runs a full Droid Exec session to help you ship faster:
+This GitHub Action powers the Factory **Droid** app. It watches your pull requests for supported commands and runs a full Droid Exec session to help you ship faster:
 
 - `@droid fill` — turns a bare pull request into a polished description that matches your template or our opinionated fallback.
 - `@droid review` — performs an automated code review, surfaces potential bugs, and leaves inline comments directly on the diff.
+- `@droid security` — performs an automated security review using STRIDE methodology, identifying vulnerabilities and suggesting fixes.
+- `@droid security --full` — performs a full repository security scan and creates a PR with the report.
 
 Everything runs inside GitHub Actions using your Factory API key, so the bot never leaves your repository and operates with the permissions you grant.
 
 ## What Happens When You Tag `@droid`
 
-1. **Trigger detection** – The action scans issue comments, PR descriptions, and review comments for `@droid fill` or `@droid review`.
+1. **Trigger detection** – The action scans issue comments, PR descriptions, and review comments for `@droid` commands.
 2. **Context gathering** – Droid collects the PR metadata, existing comments, changed files, and any PR description template in your repository.
-3. **Prompt generation** – We compose a precise prompt instructing Droid what to do (fill or review) and which GitHub MCP tools it may use.
-4. **Execution** – The action runs `droid exec` with full repository context. MPU tools are pre-registered so Droid can call the GitHub APIs safely.
-5. **Results** – For fill, Droid updates the PR body. For review, it posts inline feedback and a summary comment under the original request.
+3. **Prompt generation** – We compose a precise prompt instructing Droid what to do and which GitHub MCP tools it may use.
+4. **Execution** – The action runs `droid exec` with full repository context. MCP tools are pre-registered so Droid can call the GitHub APIs safely.
+5. **Results** – For fill, Droid updates the PR body. For review/security, it posts inline feedback and a summary comment.
 
 ## Installation
 
@@ -22,7 +24,9 @@ Everything runs inside GitHub Actions using your Factory API key, so the bot nev
 2. **Create a Factory API Key**
    - Generate a token at [https://app.factory.ai/settings/api-keys](https://app.factory.ai/settings/api-keys) and save it as `FACTORY_API_KEY` in your repository or organization secrets.
 3. **Add the Action Workflows**
-   - Create two workflow files under `.github/workflows/` to separate on-demand tagging from automatic PR reviews.
+   - Create two workflow files under `.github/workflows/` to separate on-demand tagging from automatic PR reviews, based on your needs.
+
+### Setup
 
 `droid.yml` (responds to explicit `@droid` mentions):
 
@@ -68,7 +72,9 @@ jobs:
           factory_api_key: ${{ secrets.FACTORY_API_KEY }}
 ```
 
-`droid-review.yml` (runs automatic reviews when PRs are ready):
+Once committed, tagging `@droid fill`, `@droid review`, or `@droid security` on an open PR will trigger the bot automatically.
+
+`droid-review.yml` (automatic reviews on PRs):
 
 ```yaml
 name: Droid Auto Review
@@ -78,29 +84,137 @@ on:
     types: [opened, ready_for_review, reopened]
 
 jobs:
-  droid-review:
+  prepare:
     if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     permissions:
       contents: write
       pull-requests: write
       issues: write
       id-token: write
-      actions: read
+    outputs:
+      comment_id: ${{ steps.prepare.outputs.comment_id }}
+      run_code_review: ${{ steps.prepare.outputs.run_code_review }}
+      run_security_review: ${{ steps.prepare.outputs.run_security_review }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5
         with:
           fetch-depth: 1
 
-      - name: Run Droid Auto Review
-        uses: Factory-AI/droid-action@v1
+      - name: Prepare
+        id: prepare
+        uses: Factory-AI/droid-action/prepare@v1
         with:
           factory_api_key: ${{ secrets.FACTORY_API_KEY }}
           automatic_review: true
+          automatic_security_review: true
+
+  code-review:
+    needs: prepare
+    if: needs.prepare.outputs.run_code_review == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Run Code Review
+        uses: Factory-AI/droid-action/review@v1
+        with:
+          factory_api_key: ${{ secrets.FACTORY_API_KEY }}
+          tracking_comment_id: ${{ needs.prepare.outputs.comment_id }}
+          output_file: ${{ runner.temp }}/code-review-results.json
+
+      - name: Upload Results
+        uses: actions/upload-artifact@v4
+        with:
+          name: code-review-results
+          path: ${{ runner.temp }}/code-review-results.json
+          if-no-files-found: ignore
+
+  security-review:
+    needs: prepare
+    if: needs.prepare.outputs.run_security_review == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Run Security Review
+        uses: Factory-AI/droid-action/security@v1
+        with:
+          factory_api_key: ${{ secrets.FACTORY_API_KEY }}
+          tracking_comment_id: ${{ needs.prepare.outputs.comment_id }}
+          output_file: ${{ runner.temp }}/security-review-results.json
+
+      - name: Upload Results
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-review-results
+          path: ${{ runner.temp }}/security-review-results.json
+          if-no-files-found: ignore
+
+  combine:
+    needs: [prepare, code-review, security-review]
+    if: |
+      always() &&
+      needs.prepare.outputs.run_code_review == 'true' &&
+      needs.prepare.outputs.run_security_review == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Download Code Review Results
+        uses: actions/download-artifact@v4
+        with:
+          name: code-review-results
+          path: ${{ runner.temp }}
+        continue-on-error: true
+
+      - name: Download Security Review Results
+        uses: actions/download-artifact@v4
+        with:
+          name: security-review-results
+          path: ${{ runner.temp }}
+        continue-on-error: true
+
+      - name: Combine Results
+        uses: Factory-AI/droid-action/combine@v1
+        with:
+          factory_api_key: ${{ secrets.FACTORY_API_KEY }}
+          tracking_comment_id: ${{ needs.prepare.outputs.comment_id }}
+          code_review_results: ${{ runner.temp }}/code-review-results.json
+          code_review_status: ${{ needs.code-review.result }}
+          security_review_results: ${{ runner.temp }}/security-review-results.json
+          security_review_status: ${{ needs.security-review.result }}
 ```
 
-Once committed, tagging `@droid fill` or `@droid review` on an open PR will trigger the bot automatically, and non-draft PRs will also receive automatic reviews if `droid-review.yml` is enabled.
+Set `automatic_review` and `automatic_security_review` to control which reviews run automatically on non-draft PRs.
 
 ## Using the Commands
 
@@ -116,17 +230,64 @@ Once committed, tagging `@droid fill` or `@droid review` on an open PR will trig
 - Droid inspects the diff, prioritizes potential bugs or high-impact issues, and leaves inline comments directly on the changed lines.
 - A short summary comment is posted in the original thread highlighting the findings and linking to any inline feedback.
 
-## Configuration Essentials
+### `@droid security`
+
+- Mention `@droid security` in a PR comment.
+- Droid performs a security-focused review using STRIDE methodology (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege).
+- Findings include severity levels, CWE references, and suggested fixes.
+- Security reviews run once per PR to avoid duplicate scans on subsequent commits.
+
+### `@droid security --full`
+
+- Performs a full repository security scan (not just PR changes).
+- Creates a new branch with a security report at `.factory/security/reports/security-report-{date}.md`.
+- Opens a PR with findings and auto-generated patches where possible.
+- Useful for scheduled security audits.
+
+## Configuration
+
+### Core Inputs
+
+| Input             | Purpose                                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------------------ |
+| `factory_api_key` | **Required.** Grants Droid Exec permission to run via Factory.                                         |
+| `github_token`    | Optional override if you prefer a custom GitHub App/token. By default the installed app token is used. |
+
+### Review Configuration
+
+| Input              | Default | Purpose                                                                       |
+| ------------------ | ------- | ----------------------------------------------------------------------------- |
+| `automatic_review` | `false` | Automatically run code review on PRs without requiring `@droid review`.       |
+| `review_model`     | `""`    | Override the model used for code review (e.g., `claude-sonnet-4-5-20250929`). |
+| `fill_model`       | `""`    | Override the model used for PR description fill.                              |
+
+### Security Configuration
+
+| Input                         | Default  | Purpose                                                                                                           |
+| ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `automatic_security_review`   | `false`  | Automatically run security review on PRs without requiring `@droid security`.                                     |
+| `security_model`              | `""`     | Override the model used for security review. Falls back to `review_model` if not set.                             |
+| `security_severity_threshold` | `medium` | Minimum severity to report (`critical`, `high`, `medium`, `low`). Findings below this threshold are filtered out. |
+| `security_block_on_critical`  | `true`   | Submit `REQUEST_CHANGES` review when critical severity findings are detected.                                     |
+| `security_block_on_high`      | `false`  | Submit `REQUEST_CHANGES` review when high severity findings are detected.                                         |
+| `security_notify_team`        | `""`     | GitHub team to @mention on critical findings (e.g., `@org/security-team`).                                        |
+| `security_scan_schedule`      | `false`  | Enable scheduled security scans for `schedule` events.                                                            |
+| `security_scan_days`          | `7`      | Number of days of commits to scan for scheduled security scans.                                                   |
+
+## Security Skills
+
+The security review uses specialized Factory skills installed from the public `Factory-AI/skills` repository:
+
+- **threat-model-generation** – Generates STRIDE-based threat models for repositories
+- **commit-security-scan** – Scans code changes for security vulnerabilities
+- **vulnerability-validation** – Validates findings and filters false positives
+- **security-review** – Comprehensive security review and patch generation
 
-| Input             | Purpose                                                                                                                                      |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `factory_api_key` | **Required.** Grants Droid Exec permission to run via Factory.                                                                               |
-| `github_token`    | Optional override if you prefer a custom GitHub App/token. By default the installed app token is used.                                       |
-| `review_model`    | Optional. Override the model used for code review (e.g., `claude-sonnet-4-5-20250929`, `gpt-5.1-codex`). Only applies to review flows.       |
-| `fill_model`      | Optional. Override the model used for PR description fill (e.g., `claude-sonnet-4-5-20250929`, `gpt-5.1-codex`). Only applies to fill flows. |
+These skills are automatically installed when running security reviews.
 
 ## Troubleshooting & Support
 
 - Check the workflow run linked from the Droid tracking comment for execution logs.
 - Verify that the workflow file and repository allow the GitHub App to run (branch protections can block bots).
+- Security reviews run once per PR. If you need to re-run, close and reopen the PR or use `@droid security` explicitly.
 - Need more detail? Start with the [Setup Guide](./docs/setup.md) or [FAQ](./docs/faq.md).