Panda Suite Docs
v1.9.2GitHub ↗
Panda Suite / Red command reference

Command reference

Three mechanisms

Mechanism Real behavior
Agent prompt Selected skill interprets mode, target and constraints using host tools; not a shell process.
Python helper red.py help, request, scan-report and the retained offline commands execute deterministic local operations. panda-red has no network-capable helper.
Installation panda-suite install/update or a host plugin command copies/loads definitions; it does not execute modes. npx skills is not a panda-red executor.

Agent syntax below is an instruction contract, not a universal positional-argument API. Helper request validation and host discovery are verified separately; model execution of agent prompts remains Not Run. For plugins substitute the names in installation; natural language expressing the same fields works.

Agent help and inputs

$panda-red help lists modes, inputs, outputs and boundaries. $panda-red help scan or help bounty gives focused help. Help creates no case or scan. Unknown mode/options return supported choices; never silently switch workflows. A bare path with no clear question gets a bounded read-only overview or targeted clarification.

Mode / agent cue Required input Optional context Expected saved outputs Common failure / boundary
$panda-red scan TARGET Local repository directory Depth, filters, format, exclusions, tools restrictions SECURITY_SCAN.md, canonical findings.json, scan-metadata.json Invalid path, missing/erroring tools, unsupported report; local static analysis only unless separately authorized.
$panda-red recon TARGET Repository, asset inventory or supplied evidence Exact scope, observation dates ATTACK_SURFACE.md, asset-inventory.json, RECON_REPORT.md Unknown reachability/ownership; no DNS/HTTP from passive collection.
$panda-red simulate TARGET Approved lab/fixtures and invariant Synthetic accounts, negative/control pair, telemetry SIMULATION_REPORT.md, simulation-results.json; detection report when supported Missing authorization/environment; no uncontrolled exploit or third-party data.
$panda-red bounty TARGET Program policy and engagement Explicit targets, permitted techniques and disclosure rules BUG_BOUNTY_REPORT.md Unclear policy/authority means offline draft; no submission or payout claim.

Save only applicable reports at requested destinations. An answer-only request creates none. Hunt, incident, verify and intel belong to panda-blue; automated active simulation and integration adapters remain deferred.

Scan options

Option Values / default Meaning
--depth quick / deep; quick Agent analysis prioritization; helper inventory budgets differ, not a new SAST engine.
--severity informational, low, medium, high, critical; informational Minimum Markdown/summary display severity; canonical JSON remains complete. Case-insensitive.
--format markdown, json, both; both Views; canonical findings.json and metadata are always retained. JSON-only omits Markdown.
--output New directory Explicit report root. Default is a fresh private .panda-suite/red/reports/scans/<scan-id>/.
--exclude Repeat relative path/glob Explicit exclusions; traversal/absolute patterns refused. .git is excluded by default; vendor/generated sources are not silently dropped.
--offline Default enabled No remote scanner operations/rules/advisories/uploads. Cannot make arbitrary tools safe.
--no-tools Default false Manual/static agent work; helper report imports remain allowed. No automatic tool launch even when false.

Actual helper commands

Run python3 skills/panda-red/scripts/red.py --help for the implemented shell parser. Use the existing .venv/bin/python when schema validation is needed.

Subcommand Behavior / requirements
help [MODE] Four-mode guidance; unsupported topic exits 2. No dependency installation.
request MODE TARGET [scan options] Parse/validate a structured agent request and existing local target; outputs executed=false. Does not execute the requested workflow.
scan-report TARGET [scan options] Bounded local discovery, supplied-result normalization and private report publication. Does not discover vulnerabilities itself or run producers.
validate KIND FILE KIND is engagement, case, asset, finding, evidence or scan-metadata.
inventory ENGAGEMENT ASSETS Retained supplied inventory reconciliation; no collection/crawling.
scope ENGAGEMENT URL --resolutions FILE --technique NAME Retained offline eligibility check; optional supplied redirects/window/budget observations. Never authority or a target request.
integrity CASE --root DIRECTORY Retained bounded hash checks under authorized trusted roots; no originals changed.
transition CASE --to STATE --reason TEXT --at OFFSET_TIMESTAMP Retained immutable lifecycle transform to stdout.
render CASE Retained conservative enum/index/count summary. New scan cases can also be summarized.

Scan-report accepts repeated --security-report FILE, --semgrep-report FILE and --gitleaks-report FILE. Inputs are supplied local JSON, not producer commands. It validates source containment/exclusions and actual line ranges, preserves supplied Security IDs/assessments as imported claims, and treats scanner matches as Potential concern/Unknown confidence. Unknown mappings, producer errors, stale paths/ranges, links and malformed records are refused visibly. It does not invoke a model.

--redactions FILE supplies a private JSON array of exact sensitive values (minimum four characters); do not put secrets on command lines. Gitleaks Secret fields are used for masking then omitted; raw messages/snippets are not copied. Common token, assignment and private-key patterns are also masked. Review unknown narrative/paths.

--correlations FILE accepts reviewed groups like [{"primaryId":"SEC-id","duplicates":["F-id"],"reason":"Reviewed same root cause"}]. The primary assessment stays unchanged, aliases/provenance/evidence and original producer severity/confidence/status notes survive. Cross-rule semantic equivalence is not inferred from nearby lines. Input cycles, missing IDs and partial merges are refused. Canonical JSON preserves all distinct findings and correlated aliases.

Exit behavior and errors

Helper result Exit Meaning
Help, valid request, successful transform/normalization 0 Operation completed; never implies security or absence of findings.
Invalid command/options, path/scope/schema/dependency, denied output or collision 2 Refused/error; diagnostic gives category and corrective direction without input values.
Scan-report with refused input(s), including producer error reports 3 Bundle records Partial processing; other valid inputs survive. Assessment remains Partial.
Retained scope/integrity negative or unavailable outcome 2 Ineligible/mismatch/inconclusive; never a successful security check.

Finding severity and count never determine these normalizer exits. Agent scan statuses include completed in stated scope, findings detected, partial, missing tool, invalid path, unsupported input, permission denied, scope violation, timeout and scanner failure. Actual scanners have their own installed-version exit semantics; record them separately. Helper metadata cannot claim scanner execution.

Discovery is capped at 128 files/5,000 entries/8 MiB for quick and 2,048 files/20,000 entries/32 MiB for deep; each file/report is at most 1 MiB. At most 16 reports and 1,000 rows per report are accepted. Caps/skips are visible. Source hashes and line presence prove location consistency, not exploitability. Trusted non-concurrent roots are assumed; these checks are not a sandbox or a race-proof filesystem authority boundary. Private output uses exclusive creation; metadata publishes last, and missing metadata means incomplete publication.