Iterion

Appearance

Like what we’re building? Star on GitHub

References bootstrap — deepsec + harness clones ​

Seki's external-security-tools skill uses a local references directory for two upstream projects; --var enable_deepsec=true itself requires the deepsec CLI on PATH, while its optional reference checkout only improves the missing-CLI diagnostic:

This page covers how to clone them and where Seki looks for them. The deepsec clone is optional documentation/diagnostics; the runtime executable is the installed CLI.

Default location ​

~/lab/ai/references/
├── deepsec/                                  (vercel-labs/deepsec, Apache-2.0)
├── defending-code-reference-harness/         (anthropics, reference impl)
├── COMPARISON.md                             (cross-tool gap analysis)
└── README.md                                 (what this dir is for)

Override via the ITERION_REFERENCES_ROOT env var when you want to keep the clones elsewhere:

bash
export ITERION_REFERENCES_ROOT=$HOME/work/refs
# Seki then resolves $ITERION_REFERENCES_ROOT/deepsec and
# $ITERION_REFERENCES_ROOT/defending-code-reference-harness

The run_deepsec_scanner tool node in bots/sec-audit-source/main.bot reads $ITERION_REFERENCES_ROOT (bare — the engine expands braced ${NAME:-default} forms in tool commands at launch, from the engine environment, so the body must not carry them); unset, it falls back to the bot var deepsec_root, which defaults to "${HOME}/lab/ai/references/deepsec" (override with --var deepsec_root=...). The variable is read from the environment the tool node runs in: the engine's on a non-sandboxed runner, the sandbox container's when tool nodes run sandboxed. It is consulted only after command -v deepsec fails, to name the reference checkout in the graceful degradation envelope; the node never executes cli.mjs, dist/cli.mjs, or another file from that clone.

Bootstrap ​

bash
# 1. Create the references dir
mkdir -p ~/lab/ai/references
cd ~/lab/ai/references

# 2. Clone both references (optional for deepsec, useful for inspection)
git clone https://github.com/vercel-labs/deepsec.git
git clone https://github.com/anthropics/defending-code-reference-harness.git

# 3. Ensure the executable Seki actually calls is present (the pinned sec
# sandbox image provides it); install the matching version only deliberately
command -v deepsec

# 4. (Optional but recommended) pin the reference clones to known-good shas
git -C deepsec checkout e3c8f05a0a72e3466e82bdcdda86e7c65fc2ad3b
git -C defending-code-reference-harness checkout 9e0f6c6cd54fc3b8ce79708e8208d862634a2624

The pinned shas above are the ones the iterion COMPARISON.md was written against. Bumping them is fine but treat it as a Seki-affecting change: deepsec's CLI surface or the harness's slash-command shape can shift between commits.

CLI and Node 22 requirements (deepsec only) ​

Seki calls the installed deepsec executable, which requires Node ≥ 22. The reference clone does not satisfy either requirement. Check:

bash
command -v deepsec  # must resolve
node --version      # must report v22.x or higher

The run_deepsec_scanner tool node checks the Node major version before calling the CLI and degrades gracefully (envelope carries errors[], run never fails) when it is missing or <22:

deepsec unavailable: node binary not found on PATH
deepsec unavailable: node <X> < 22 (deepsec requires Node 22+)

The harness has no Node requirement of its own; its slash-command skills run inside the local claude CLI.

What --var enable_deepsec=true does ​

When set, the workflow:

  1. Probes for a deepsec binary (command -v deepsec). When absent, the tool node returns a graceful-degrade envelope citing the reference clone path so the operator knows where it would have looked.
  2. Initialises a per-run deepsec workspace at <scan_dir>/deepsec-workspace/ (idempotent — only runs deepsec init when deepsec.config.ts is absent).
  3. Scans the target workspace with deepsec's ~110-matcher regex pack (deepsec scan).
  4. Processes up to --var deepsec_process_limit files (default 50) at concurrency --var deepsec_concurrency (default 4). This caps the LLM cost — deepsec's per-file batches can run $0.05–$0.30 with Opus.
  5. Exports the JSON under a per-run subdirectory derived from --var deepsec_out — <scan_dir>/deepsec-out-<run.id>/deepsec.json by default — and publishes that path in its json_paths.deepsec. The flat <scan_dir>/deepsec.json of releases before 0.1.4 is removed by the first deep-scan pass that gets past its preflight and read by no node.
  6. Triage reads that JSON through the published json_paths (or the findings_budget.inline transport on backends with no shared filesystem) and maps each finding to a Seki candidate per the field-mapping table in scanner-deepsec.md.

Provider selection (no API key plumbed), in precedence order:

  • --var deepsec_agent=<claude|codex|pi>, when set, wins. deepsec has its own backend system, unrelated to iterion's, and this is the only way to say which of its plugins investigates. --var deepsec_model=<model> pins the model on any of the three routes below (deepsec process --model is accepted whether or not --agent is passed); left empty, deepsec keeps its own per-agent default. An explicit agent deliberately outranks the gateway probe: the probe is a detection, the var is a decision, and it decides which subscription the pass draws on — the deep scan is the dominant consumer of a run and no engine counter meters it. Both values reach deepsec as bare words, so both refuse a leading dash — it would read as a second flag and the name would silently become the next argument. Beyond that the two differ on purpose: deepsec_agent is held to A-Za-z0-9._- (no /, so an agent name cannot become a plugin path), while deepsec_model refuses only what cannot survive an unquoted expansion — whitespace and the glob characters *?[. Provider model ids legitimately carry : and @ (us.anthropic.claude-opus-4-8-v1:0, anthropic/claude-opus-4@20250101), and refusing one would degrade the whole deep scan rather than drop a flag.
  • Otherwise, if AI_GATEWAY_API_KEY or DEEPSEC_API_KEY is set in the run env, deepsec routes through the Vercel AI Gateway (its native preflight), which picks the model itself.
  • Otherwise the tool node passes --agent claude so deepsec reuses the local claude CLI subscription. The sec sandbox mounts ${localEnv:HOME}/.claude into the container at /home/devbox/.claude so the OAuth credentials are visible to the spawned CLI. codex is the symmetric route onto a ChatGPT subscription: deepsec reads ~/.codex/auth.json when no OPENAI_API_KEY is set, and the platform mounts that file too.

Whichever route is taken is echoed into the node's env.log, which travels out in the envelope's errors[] — deepsec is absent from backends_used, so that line is the only record of which agent ran.

bash
# Default behaviour
devbox run -- iterion run bots/sec-audit-source/main.bot \
  --var workspace_dir=$(pwd) \
  --var enable_deepsec=true

# Override the references root + raise the process limit
ITERION_REFERENCES_ROOT=$HOME/work/refs \
  devbox run -- iterion run bots/sec-audit-source/main.bot \
  --var workspace_dir=$(pwd) \
  --var enable_deepsec=true \
  --var deepsec_process_limit=200 \
  --var deepsec_concurrency=8

When deepsec is disabled (the default), the deepsec_gate routes straight to scan_join and the workflow is byte-identical to a pre-enhancement-4 run. Triage's deepsec_scan input resolves to an empty object via if(vars.enable_deepsec, …, '') so the runtime never references a node that did not run.

scan_health surfaces a missing deepsec.json to report_card so a degraded deepsec run shows up in the coverage banner — it is NOT counted toward min_generic_scanners (so a missing deepsec NEVER hard-fails the run — only flags as degraded). Because the floor counts the always-on trio alone, a min_generic_scanners above 3 is clamped to 3 and reported (min_generic_requested / min_generic_clamped in the envelope, a NOTE in the report).

On-demand harness invocation (external-security-tools skill) ​

The harness's pipeline is C/C++/ASAN driven — not applicable to Go/TS repos. But its slash-command skills (/threat-model, /vuln-scan, /triage, /patch) are language-agnostic and run via the local claude CLI.

The external-security-tools skill is the on-demand entry point — used as a cross-check oracle when a Seki verdict is uncertain, or as a fallback for languages Seki's scanners do not cover. Invocation shape (always --auto for headless):

bash
cd <workspace>

# Bootstrap a threat model (writes THREAT_MODEL.md in the target dir)
claude --print "/threat-model bootstrap ."

# Run the harness's adversarial triage on Seki's own VULN-FINDINGS.json
claude --print "/triage VULN-FINDINGS.json --auto --repo ."

# Static-mode patch on the top 5
claude --print "/patch TRIAGE.json --repo . --top 5"

Cross-check outputs are copied to .sec-audit/cross-check/<ts>/ to keep them out of the workspace root.

Both tools have the same read-only constraint Seki enforces: harness /patch writes diffs to ./PATCHES/ (never git apply); deepsec writes only scanner JSON and FileRecord caches. Seki forwards their output through its own normalisation layer — it does not blindly trust either.

Attribution + licenses ​

Both clones are governed by their upstream licenses. Read them in the clones themselves:

bash
less ~/lab/ai/references/deepsec/LICENSE                                # Apache-2.0
less ~/lab/ai/references/defending-code-reference-harness/LICENSE       # Apache-2.0 (reference impl)
less ~/lab/ai/references/deepsec/NOTICE                                 # NOTICE file

Seki's bundled ports of the harness skills (threat-model, vuln-scan, triage, patch) carry an attribution: frontmatter field naming the upstream skill and the iterion-side adaptation. See HARNESS-ATTRIBUTION.md for the full mapping.

Troubleshooting ​

SymptomLikely causeCheck
deepsec unavailable: node binary not found on PATHNode 22 not in the sandbox imagenode --version inside the sec sandbox; rebuild iterion-sandbox-sec
deepsec unavailable: node <N> < 22 (deepsec requires Node 22+)Old NodeUpgrade Node ≥ 22
deepsec unavailable: deepsec CLI not on PATH (reference clone exists at <path>…)The clone is there but no global installPut deepsec on PATH, normally by rebuilding the sec sandbox image; install globally only as a deliberate host override
deepsec unavailable: neither global deepsec CLI on PATH nor reference clone at <path>Neither path resolvesPut deepsec on PATH / rebuild the image; a clone under $ITERION_REFERENCES_ROOT/deepsec only makes the diagnostic more precise
claude CLI not on PATH when invoking the harness skills@anthropic-ai/claude-code not installedThe sec sandbox's post_create hook auto-installs it; outside the sandbox, npm install -g @anthropic-ai/claude-code

See also ​