---
name: appsec-agent
description: Run an end-to-end OpenTaint application-security analysis while owning the long project build and scans and delegating each other pipeline stage. Use when the user asks to find vulnerabilities, or scan an application for security issues
license: Apache-2.0
metadata:
  author: opentaint
  version: "0.3.0"
---

# AppSec Agent

Orchestrate an end-to-end OpenTaint security analysis. Keep the long project build and every full-project scan in this main session; delegate each bounded source, approximation, sink, triage, and PoC stage to an `orchestrate-stage` subagent, which owns its leaf fan-out and joins.

OpenTaint is a whole-program, interprocedural, field-sensitive alias analysis SAST. The run produces confirmed vulnerabilities plus reusable project-specific rules and approximations under one self-contained `.opentaint/` directory at the project root.

## Setup

### 1. Confirm the toolchain

Confirm `opentaint` is on PATH with `opentaint -v`. If it's missing, don't proceed silently — tell the user and offer the install command for their platform, run an install only on explicit confirmation:

- macOS / Linux, in order: `brew install --cask seqra/tap/opentaint` · `npm install -g @seqra/opentaint`
- Windows: `npm install -g @seqra/opentaint`

After installing, run `opentaint health` to confirm everything's resolved.

### 2. Confirm agent nesting

This workflow requires two subagent levels: MAIN → stage orchestrator → leaf. Confirm the harness permits depth 2 before starting; otherwise ask the user to enable it.

### 3. Determine the language

Read the project's build files to fix the target language — Maven/Gradle → java, `go.mod` → go, and so on. Record it at bootstrap; stage orchestrators pass it to language-coupled leaves.

### 4. Choose the workflow

Ask the user for both levels together:

1. Scan level — `lite` · `normal` · `deep`
   - lite — build + scan (expected, when there are already existing artifacts)
   - normal — build + scan + custom approximations
   - deep — build + scan + custom approximations + custom rules
   - recommend by what's on disk: a cold start (no `.opentaint` artifacts) → deep; a prior run's artifacts already present → lite
2. Triage level — `static` · `dynamic`
   - static — classify findings from the model, no running app
   - dynamic — static + PoC per confirmed TP. This launches a few test services on the user's machine (local instances and ports), torn down at the end of the run. Make that clear in the option

### 5. Bootstrap

Seed the run state and the working tree with the chosen levels and language:

```bash
uv run <skill-dir>/scripts/generate.py init --scan-level <lite|normal|deep> --triage-level <static|dynamic> --language <lang>
```

It writes `state.yaml`, seeds `history.yaml`, creates the `.opentaint/` tree, and generates `tracking/rules/tags.yaml`. A fresh tree inventories builtin lib tags, a resumed tree refreshes from builtin + `.opentaint/rules`. Use `generate.py tags` only to recover that registry explicitly.

## Workflow

The run is one fixed pipeline; the selected levels determine which phases are in scope. Use `uv run <skill-dir>/scripts/get_status.py` to choose the next action:

```
build                       → MAIN: build
discover / source_rules     → stage subagent: sources
scan                        → MAIN: scan
approximations              → stage subagent: approx-round, then MAIN: rescan; repeat
sink_rules                  → stage subagent: sinks, then MAIN: rescan
triage                      → stage subagent: triage
poc                         → stage subagent: poc
```

### Build in MAIN

When status reports `build`, load and follow the `build-project` skill in this main session. Pass any language-specific build fields already present in `state.yaml` as `build-hints`. Run its long build command through the harness's main-session background-command facility and wait for its completion event.

After a successful build, write the language-specific build fields named by the selected `build-project` reference into `.opentaint/tracking/state.yaml`. Record `model_commit` as the full HEAD only when no source file is uncommitted, otherwise set it to null. Build non-convergence blocks the run because no later phase can proceed without the model.

### Scan in MAIN

When status reports `scan`, or a stage returns with a rescan pending, load and follow the `run-scan` skill in this main session. Start the scan with the harness's main-session background-command facility, keep the engine's self-timeout, add a 1200-second outer backstop, and wait for the process completion event.

A valid `.opentaint/results/report.sarif` means the scan completed, including exit 254 after an engine timeout. Record `max_memory: 16G` when the scan had to bump memory and reuse it on later scans. If no SARIF exists after the allowed retry/backstop, follow the repair path below for a malformed rule/approximation; otherwise dispatch `orchestrate-stage` with `stage: escalation` and the scan `setup` to write the scan-wide resource issue, then stop.

When a scan or later stage reports a malformed approximation, unloadable created rule, ineffective join, or a created rule's false positive/negative, route the exact diagnosis and artifact path/id to the responsible stage agent per Dispatching, then scan again in MAIN.

After every build, scan, or stage return, run `uv run <skill-dir>/scripts/get_status.py` once to choose the next action. Use `--full` at run start, on resume, or when the brief output does not settle the question.

## Dispatching

Dispatch exactly one stage-orchestrator subagent for each stage invocation:

```
Invoke the Skill orchestrate-stage first, then follow its instructions precisely
Inputs:
  stage: <sources|approx-round|sinks|triage|poc|escalation>
```

For a `deep` approximation round, also pass `sinks: true`. A subagent inherits the project-root working directory, so omit `project-root`.

Stage context:

- `sources` — discover dependency sources and author tag-grouped source rules
- `approx-round` — classify and build one dropped-method frontier; use a fresh agent for each new frontier
- `sinks` — author classified sink rules and wire the joins
- `triage` — classify the latest findings and refresh the vulnerability report
- `poc` — reproduce confirmed findings and add the outcomes to the report
- `escalation` — repair or settle a stage artifact, or report a scan-wide no-SARIF failure

Keep each agent id until the next scan validates its artifacts. On a stage-owned error, resume that agent with `stage: escalation`, the exact error, and the artifact path/id. If its thread is unavailable, start a re-entrant `orchestrate-stage` agent with that diagnosis.

Dispatch each subagent fresh, don't fork context into it. Then wait for it natively, don't monitor or poll every minute. If the harness forces a wait timeout, set it to ~1h and re-wait when it returns.

## State and resumption

Use this ownership map to route work and scan errors:

```
.opentaint/
  project/             MAIN build
  results/             MAIN scan
  rules/               sources or sinks stage
  pass-through/        approximation stage
  dataflow/            approximation stage
  tracking/state.yaml  MAIN run knobs
  tracking/            stage agents, leaves, and join scripts otherwise
  vulnerabilities.md   triage / PoC stage
  issues/               escalation stage
```

The tree is long-lived. On resume, reuse `DONE` artifacts; `get_status.py` derives the next phase from disk. Existing rules and approximations apply to every scan.

`state.yaml` shape:

```yaml
scan_level: deep
triage_level: dynamic
language: <language>
model_commit: 0123456789abcdef0123456789abcdef01234567
max_memory: null
```

The selected `build-project` language reference may define additional build fields; preserve them on resume and pass them back as `build-hints`.

## Key constraints

- read pipeline state through `<skill-dir>/scripts/get_status.py`, not by hand — don't re-derive it with glob/grep/`python3 -c`/yaml scans over `.opentaint/tracking`, `results`, or the `*.yaml`, nor open finding/unit/SARIF files just to review progress. If its output doesn't settle the question, re-run it with `--full` before opening any file
- don't author or edit stage-owned artifacts or tracking; MAIN writes only `model_commit`, `max_memory`, and build fields defined by the selected `build-project` reference in `state.yaml`
- keep one generated project model for the run; never hand-edit or replace it mid-analysis — fix the build and rebuild before starting a new run