run

What this skill does

# AppSec Run -- Smart Orchestrator

The primary way to run security analysis. Detects the project's tech stack,
selects the most relevant scanners and category skills, runs everything in
parallel, consolidates results, and optionally launches red team simulation.

This skill is the automated version of `/appsec:start`. Where `start` gives
recommendations and lets the user choose, `run` makes the choices and
executes them. It handles ALL cross-cutting flags and adapts its behavior
to the detected codebase.

## Supported Flags

Read [`../../shared/schemas/flags.md`](../../shared/schemas/flags.md) for the
full flag specification. This orchestrator supports ALL cross-cutting flags.

| Flag | Orchestrator Behavior |
|------|----------------------|
| `--scope` | Propagated to all scanners and subagents. Default `changed`. |
| `--depth quick` | Scanners only. No code analysis subagents. Fastest mode. |
| `--depth standard` | Scanners + relevant category subagents (default). |
| `--depth deep` | Standard + cross-file data flow tracing + additional frameworks. |
| `--depth expert` | Deep + red team agent simulation with DREAD scoring. |
| `--severity` | Applied during consolidation to filter merged output. |
| `--format` | Applied to final consolidated output. |
| `--only A01,S,secrets` | Run only the listed tools/categories. Accepts OWASP codes (A01-A10), STRIDE letters (S,T,R,I,D,E), and tool names (secrets, deps, surface). |
| `--fix` | Propagated to subagents; each produces fix suggestions inline. |
| `--quiet` | Suppress explanations, output findings only. |
| `--explain` | Add learning material per finding. |
| `--persona all\|insider\|apt\|...` | Select red team personas (requires `--depth expert`). |
| `--skip-redteam` | Skip red team phase even in expert mode. |

## Workflow

### Phase 1: Detection (Main Agent)

Execute these steps sequentially in the main agent context before launching
any subagents. Use Glob, Grep, Read, and Bash tools to gather evidence.

#### Step 1.1: Check for Cached Assessment

Look for `.appsec/start-assessment.json`. If it exists and is fresh (less
than 24 hours old, and manifest files have not changed since), load it and
skip to Step 1.5.

The cached assessment is also stale if any of:
- Scanner availability has changed (a new scanner was installed or one was removed)
- `.appsec/config.yaml` has been modified since the assessment
- The current git branch differs from the branch recorded in the assessment

If no cache exists or it is stale, run Steps 1.2 through 1.4.

#### Step 1.2: Detect Tech Stack

Read project manifests to determine languages, frameworks, and databases.
Check for each of these files using Glob:

| File Pattern | Reveals |
|-------------|---------|
| `package.json` | Node.js, npm dependencies |
| `requirements.txt`, `Pipfile`, `pyproject.toml` | Python |
| `go.mod` | Go |
| `Cargo.toml` | Rust |
| `Gemfile` | Ruby |
| `pom.xml`, `build.gradle`, `build.gradle.kts` | Java/Kotlin |
| `*.csproj`, `*.sln` | .NET/C# |
| `composer.json` | PHP |
| `Dockerfile`, `docker-compose.yml` | Containers |
| `serverless.yml`, `serverless.yaml` | Serverless |
| `**/*.tf` | Terraform IaC |
| `.github/workflows/*.yaml`, `.github/workflows/*.yml` | GitHub Actions CI/CD |

Read each found manifest to extract framework names and notable dependencies.

#### Step 1.3: Detect Architecture & Data Sensitivity

Scan for patterns indicating sensitive data and architecture type:

**Architecture signals:**
- API-only: route handlers without templates, OpenAPI spec
- Full-stack: template engines alongside API, React/Vue/Angular
- GraphQL: `.graphql` files, `graphql` in dependencies
- WebSocket: `ws`, `socket.io` in dependencies
- Serverless: Lambda handlers, Cloud Functions

**Data sensitivity signals:**
- PII: `email`, `phone`, `ssn`, `date_of_birth` in models
- Financial: `stripe`, `paypal`, `card_number`, `transaction`
- Health: `hipaa`, `patient`, `diagnosis`, `medical_record`
- Auth: `jwt`, `oauth`, `bcrypt`, `session`

#### Step 1.4: Detect Installed Scanners

Check PATH for known scanner binaries using Bash `which` commands. Run
these checks in parallel:

```
which semgrep && which bandit && which gosec && which brakeman
which gitleaks && which trufflehog && which trivy && which osv-scanner
which npm && which pip-audit && which cargo-audit
```

Read [`../../shared/schemas/scanners.md`](../../shared/schemas/scanners.md)
for the full scanner registry. Only mark language-specific scanners as
relevant if that language is in the detected stack.

#### Step 1.5: Build Execution Plan

Based on detected stack, data sensitivity, architecture, and installed
scanners, build an execution plan that determines:

1. **Which scanners to run** (only those installed and relevant).
2. **Which category skills to dispatch** (based on architecture and data).
3. **Which frameworks to use** (OWASP is always included; STRIDE added for
   apps with user auth; LINDDUN added when PII detected).

**Tool selection rules:**

| Condition | Tools Selected |
|-----------|---------------|
| Always | `secrets`, `misconfig`, `insecure-design` |
| Has user auth | `access-control`, `auth`, `spoofing`, `privilege-escalation` |
| Has database | `injection` |
| Has HTTP client calls | `ssrf` |
| Has dependencies | `outdated-deps` |
| Has logging/audit | `logging`, `repudiation` |
| Has CI/CD | `integrity` |
| Has crypto imports | `crypto` |
| Has PII / GDPR signals | LINDDUN categories (all 7) |
| Has GraphQL | `graphql` (specialized) |
| Has WebSocket | `websocket` (specialized) |
| Has serverless config | `serverless` (specialized) |
| Has file upload | `file-upload` (specialized) |
| Has financial/business logic | `business-logic`, `race-conditions` |
| `--depth deep` or `expert` | `attack-surface`, `data-flows`, `sans25` |
| `--depth expert` | Red team agents (see Phase 4) |

If `--only` is specified, override the automatic selection and dispatch
only the listed tools/categories.

Cache the execution plan to `.appsec/start-assessment.json` with a
timestamp for future reuse.

### Phase 2: Run Scanners (Main Agent)

Run detected scanners in the main agent context using Bash. Launch ALL
scanner commands in parallel Bash calls within a SINGLE response.

Before launching scanners, create the output directory:

```bash
mkdir -p reports/appsec/scanners
```

For each detected scanner, use the invocation pattern from
[`../../shared/schemas/scanners.md`](../../shared/schemas/scanners.md).
Redirect ALL scanner output to files — the main agent NEVER reads scanner
JSON content.

**Scanner dispatch pattern:**

```bash
# Run each scanner in parallel Bash calls — redirect output to files
semgrep scan --config auto --json --quiet <scope_path> > reports/appsec/scanners/semgrep.json 2>&1
gitleaks detect --source <scope_path> --report-format json --no-banner > reports/appsec/scanners/gitleaks.json 2>&1
npm audit --json > reports/appsec/scanners/npm-audit.json 2>&1           # if Node.js project
pip-audit --format json > reports/appsec/scanners/pip-audit.json 2>&1    # if Python project
trivy fs --format json <scope_path> > reports/appsec/scanners/trivy.json 2>&1   # if installed
```

After ALL scanners complete, check exit codes and file sizes ONLY. Do NOT
read or parse scanner JSON files in the main agent context.

```bash
# Check each scanner result — exit code + file size only
ls -l reports/appsec/scanners/*.json
```

Build a scanner status list from exit codes and file sizes:

- **Exit code 0 or 1 AND file size > 0**: Mark as `OK`.
- **Exit code > 1 AND file size > 0**: Mark as `PARTIAL (ran with warnings)`.
- **File size 0 or file missing**: Mark as `FAILED (no output)`.
- **Exit code 127 (command not found)**: Mark as `MISSING`.

**Error handling for scanners:**

- **Non-zero exit code**: Many scanners exit non-zero when they find issues
  (e.g., `npm audit` exits 1 when vulnerabilities exist). This is normal.
  Only treat it as a failure if the output file is empty (0 bytes).
- *