Skip to content

output-structure.md

Latest commit

 

History

History
312 lines (259 loc) · 16.4 KB

output-structure.md

File metadata and controls

312 lines (259 loc) · 16.4 KB
Raw

Piolium Output Structure

Piolium writes all audit artifacts under a piolium/ directory in the target repository. This file explains that directory layout and which files are meant to be read, retained, or treated as transient implementation detail.

For phase-by-phase behavior, see phase-reference.md.

Top-level layout

piolium/
  audit-state.json
  attack-surface/
  file-records/                 # optional; only with PIOLIUM_FILE_RECORDS=1
  findings-draft/
  findings/
  exports/
  final-audit-report.md
  confirmation-report.md
  confirm-workspace/
  chamber-workspace/
  adversarial-reviews/
  merge-workspace/
  quarantine/
  tmp/piolium/
  variant-summary.md

Not every command creates every path. Lite runs create audit-state.json, attack-surface/, severity-prefixed findings/<C|H|M><N>-<slug>/ directories with draft.md + poc.* + evidence/, retained draft evidence, candidate file records, and cleanup metadata. Balanced and deep runs add final-audit-report.md and per-finding report.md files via downstream review and assembly phases.

Durable outputs

These paths are the primary outputs to keep after a run:

Path Produced by Description
piolium/KNOWLEDGE-BASE.md maintainer (input, not generated) Hand-curated, authoritative project context read first by knowledge-base-builder. Legacy name piolium/INFO.md still honored as a fallback. See Maintainer-provided context.
piolium/audit-state.json all audit commands Run history, mode, status, phases, retry metadata, artifacts, commit, branch, and repository identity.
piolium/attack-surface/ lite, balanced, deep, diff, revisit, merge Durable context used by later phases: recon, advisories, KB, SAST, probes, chamber summaries, and merge summaries.
piolium/attack-surface/candidates.jsonl lite, balanced, deep, diff, revisit, longshot Ranked deterministic candidate matches used to steer later phases toward high-risk files.
piolium/attack-surface/candidates-summary.md lite, balanced, deep, diff, revisit, longshot Human-readable candidate totals, top files, and highest-ranked matches.
piolium/file-records/ optional for lite, balanced, deep, diff, revisit, longshot Per-source-file scan records with SHA-256, candidate count, risk score, and candidate snippets. Disabled by default; enable with PIOLIUM_FILE_RECORDS=1 or --plm-file-records true.
piolium/findings/ lite, balanced, deep, revisit, merge Final finding directories promoted from reviewed drafts (severity-prefixed <C|H|M><N>-<slug>/ for lite Q3 and balanced L5 onward).
piolium/exports/ export command JSON or markdown exports generated by /piolium-export.
piolium/final-audit-report.md balanced, deep, revisit, merge Consolidated final report across finalized findings.
piolium/confirmation-report.md confirm, deep P16 Confirmation verdict report for existing findings.
piolium/variant-summary.md deep Variant-search summary for confirmed findings.
piolium/attack-surface/longshot-summary.md longshot Curated, deduped summary of the hail-mary swarm output.

audit-state.json

piolium/audit-state.json is the resume and status file. It has this shape:

{
  "audits": [
    {
      "audit_id": "2026-...",
      "commit": "...",
      "branch": "main",
      "repository": "owner/repo",
      "history_available": true,
      "mode": "balanced",
      "model": "...",
      "agent_sdk": "pi",
      "started_at": "...",
      "completed_at": "...",
      "status": "complete",
      "phases": {
        "L1": {
          "status": "complete",
          "started_at": "...",
          "completed_at": "...",
          "artifacts": ["piolium/attack-surface/advisory-summary.md"],
          "attempt": 1,
          "max_attempts": 3
        }
      }
    }
  ]
}

Phase status values are pending, in_progress, complete, failed, and skipped.

attack-surface/

piolium/attack-surface/ is the durable working knowledge base. It is safe to read directly and is intentionally retained by cleanup phases.

Common files include:

File Produced by Description
lite-recon.md lite Q0 Source snapshot, manifests, frameworks, entry points, git status, and scan exclusions.
candidates.jsonl deterministic candidate scan One JSON object per candidate match, sorted by risk/noise score.
candidates-summary.md deterministic candidate scan Candidate totals, top classes, top files, and highest-ranked matches.
matcher-suggestions.json /piolium-learn Suggested custom matcher rules derived from finalized findings.
lite-q1-summary.md lite Q1 Secrets scan backend, result count, and scan notes.
lite-q2-summary.md lite Q2 Fast SAST summary.
lite-consolidation-manifest.json lite Q3 Severity-prefixed ID assignments, source draft paths, and dropped low/info entries.
lite-verification-summary.md lite Q4 Final finding counts and lite cleanup summary.
lite-cleanup-summary.json lite Q4 Removed, missing, and retained paths from lite cleanup.
advisory-summary.md balanced L1, deep P1 Advisory and dependency intelligence.
knowledge-base-report.md balanced L2, deep P3 Architecture model, trust boundaries, DFD/CFD slices, threat model, and coverage gaps.
knowledge-base-input/ knowledge-base KB0; balanced/deep with --plm-knowledge-base Immutable, cited staging copy of user-supplied external docs (manifest.json + corpus.md + sources/NNN-*), treated as untrusted data. Written only by the engine.
knowledge-base-seed.md knowledge-base KB0 Cited, security-oriented distillation of the staged external-doc corpus (sources/<file>:<line> citations); read by later phases as data to verify against source.
unauthenticated-surface.md lite Q2, balanced L2, deep P3 (seed) → deep P5 (final) The subset of the attack surface reachable by an anonymous attacker (no session/token/API key): pre-auth routes and non-route entry points, each tagged by-design / missing-guard / middleware-gap. Present in every intensity. In deep, the authz-auditor supersedes the knowledge-base-builder's seed with an exhaustive matrix-derived version.
architecture-entrypoints.md deep P3 Entry points, attacker sources, sinks, routes, and key files.
source-sink-flows-all-severities.md balanced L3, deep P4 SAST findings and source-to-sink paths.
manual-attack-surface-inventory.md balanced L4, deep P8 Manually traced routes, sources, sinks, and exploit-relevant paths.
balanced-probe-summary.md balanced L4 Balanced probe summary.
balanced-chamber-summary.md balanced L5 Balanced chamber and FP-check summary.
balanced-consolidation-manifest.json balanced L5 Severity-prefixed ID assignments, source draft paths, and dropped low/info entries.
balanced-verification-summary.md balanced L7 Final folder verification and cleanup summary.
balanced-cleanup-summary.json balanced L7 Removed, missing, and retained paths from balanced cleanup.
patch-bypass-summary.md deep P2 Git history and bypass review.
public-routes-authz-matrix.md deep P5 Authorization matrix for routes or operations.
state-concurrency-summary.md deep P6 State, idempotency, and concurrency analysis.
spec-gap-summary.md deep P7 Spec, parser, and framework contract gaps.
deep-probe-summary.md deep P8 Deep manual probe summary.
cross-service-edges.json deep P9 Machine-readable cross-service edges, or a single-service marker.
cross-service-edges.md deep P9 Human-readable cross-service data-flow report.
deep-cleanup-summary.json deep P17 Removed, missing, and retained paths from final deep cleanup.
diff-summary.md diff D1 Changed files, scope decisions, touched routes/sources/sinks, and finding pointers.
revisit-attack-surface-inventory.md revisit R5 Revisit-specific attack-surface inventory.
revisit-probe-summary.md revisit R5 Fresh revisit probe summary.
revisit-r7-chamber-summary.md revisit R7 Revisit chamber summary for R7.
revisit-r8-chamber-summary.md revisit R8 Revisit chamber summary for R8.
merge-summary.md merge M7 Merged durable context summary.
longshot-targets.json longshot X1 Per-file target list with score, language, and per-file status (pending / in_progress / complete / failed). The X2 fan-out updates this file atomically as it makes progress.
longshot-summary.md longshot X3 Curated summary: run metadata, per-anchor table, ranked curated findings, and top concerns.

findings-draft/

piolium/findings-draft/ contains candidate markdown findings before final promotion. Draft names indicate the phase that created them.

Examples:

piolium/findings-draft/
  q1-001-hardcoded-token.md
  q2-001-path-traversal.md
  p4-001-command-injection.md
  p8-001-idor.md
  p10-001-idor.md
  p12-001-idor-variant.md
  diff-001-new-ssrf.md
  r8-001-cache-poisoning.md
  longshot-a1b2c3d4-001-command-injection.md
  longshot-a1b2c3d4-000-no-finding.md
  longshot-curated-001-command-injection.md

Drafts usually include YAML frontmatter:

---
id: p10-001
phase: P10
slug: idor
severity: high
---

# Finding body

Cleanup phases retain findings-draft/ so rejected and intermediate drafts remain inspectable. Treat this directory as evidence and audit context, not the final report.

findings/

piolium/findings/<id>-<slug>/ is the final per-finding layout.

piolium/findings/
  H-001-idor/
    draft.md
    report.md
    poc.py
    poc.theoretical.md
    evidence/
      confirmed-2026-05-01T10-00-00.log

Common files:

File Description
draft.md Promoted draft with normalized frontmatter.
report.md Final disclosure-style report. This is the per-finding source of truth for confirmation mode.
poc.* Executable proof of concept, using the most natural language for the target.
poc.theoretical.md Written when a real runtime exploit cannot be executed but the exploit chain is documented.
evidence/ Commands, HTTP exchanges, logs, screenshots, or other proof collected during PoC and confirmation work.

False-positive findings may be renamed with an FP- prefix during confirmation:

piolium/findings/FP-H-001-idor/

confirm-workspace/

piolium/confirm-workspace/ stores confirmation inputs, live-run results, and cleanup summaries.

File Produced by Description
repair-summary.json confirm V1 (pre-inventory) Outcome of the report-repair pass: which findings had report.md (re)authored from draft.md, which were already complete, which failed, and which had no repair source.
findings-inventory.json confirm V1 Extracted finding metadata, exploitability classification, and poc_kind (runnable / theoretical / none) for V4/V5 routing.
env-strategies.json confirm V2 Ranked local startup and test strategies.
auth-spec.json confirm V2 Optional auth identity scaffolding.
env-connection.json confirm V3 or remote target setup Base URL, credentials/tokens when available, method used, cleanup command, and session metadata.
healthcheck-failure.log confirm V3 Startup or healthcheck failure details.
poc-results.json confirm V4 Aggregate PoC execution results.
test-mapping.json confirm V5 Generated test fallback results.
false-positive-renames.json confirm V6/V7 Finding directories renamed with an FP- prefix.
cleanup-summary.json confirm V7 Final layout checks, evidence directory creation, redaction summary, and skipped files.

Review and merge workspaces

These paths are useful for debugging and review, but some cleanup phases remove them after final artifacts are written.

Path Produced by Description
piolium/chamber-workspace/ deep P10 Review chamber transcripts and cluster index.
piolium/chamber-workspace/index.md deep P10 Index of chamber clusters and decisions.
piolium/adversarial-reviews/ deep P11 Cold false-positive verification notes.
piolium/merge-workspace/ merge Copied findings, source aliases, dedup decisions, and rename maps.
piolium/quarantine/ merge Findings excluded from final merged output because they could not be safely normalized.

Agent transcripts and temporary files

Agent sessions write transcripts under:

piolium/tmp/piolium/runs/<runId>/
  prompt.md
  transcript.jsonl
  result.md
  error.txt

These files are for debugging phase execution. Cleanup phases generally remove piolium/tmp/ after durable artifacts are written.

Output by command

Command Primary outputs
/piolium-lite attack-surface/lite-*.md, attack-surface/unauthenticated-surface.md, attack-surface/lite-consolidation-manifest.json, severity-prefixed findings/<C|H|M><N>-<slug>/ (draft.md, poc.*, evidence/), attack-surface/lite-cleanup-summary.json
/piolium-balanced attack-surface/advisory-summary.md, knowledge-base-report.md, attack-surface/unauthenticated-surface.md, SAST/probe/chamber summaries, findings/, final-audit-report.md, balanced cleanup summary
/piolium-deep Full attack-surface/ corpus, findings/, variant-summary.md, final-audit-report.md, optional confirmation-report.md, deep cleanup summary
/piolium-export exports/findings-*.json or markdown export directory with filtered finding metadata and owners
/piolium-learn attack-surface/matcher-suggestions.json, optional matchers.json
/piolium-confirm confirmation-report.md, confirm-workspace/*.json, updated findings/*/report.md, evidence logs
/piolium-diff attack-surface/diff-summary.md, findings-draft/diff-*.md
/piolium-revisit Revisit summaries under attack-surface/, new or updated findings/, regenerated final-audit-report.md
/piolium-merge merge-workspace/, merged findings/, attack-surface/merge-summary.md, final-audit-report.md, optional quarantine/
/piolium-longshot attack-surface/longshot-targets.json, attack-surface/longshot-summary.md, findings-draft/longshot-<sha8>-*.md (raw), findings-draft/longshot-curated-*.md (deduped)

What to read first

For a completed audit, start with:

  1. piolium/final-audit-report.md
  2. piolium/findings/<id>-<slug>/report.md
  3. piolium/attack-surface/knowledge-base-report.md
  4. piolium/attack-surface/unauthenticated-surface.md (all intensities — what an anonymous attacker can reach; triage pre-auth findings first)
  5. piolium/attack-surface/source-sink-flows-all-severities.md
  6. piolium/audit-state.json

For confirmation results, start with:

  1. piolium/confirmation-report.md
  2. piolium/confirm-workspace/poc-results.json
  3. piolium/confirm-workspace/test-mapping.json
  4. piolium/findings/<id>-<slug>/evidence/

Maintainer-provided context (KNOWLEDGE-BASE.md)

piolium/KNOWLEDGE-BASE.md is an input, not an output: a hand-curated, project-specific context file (typically 50–100 lines) a maintainer checks into the target repo. When present it is treated as authoritative — knowledge-base-builder inlines it verbatim and skips re-deriving what it covers. The extension sets PIOLIUM_KNOWLEDGE_BASE_AVAILABLE (true/false) per command so in-process sub-agents can branch on its presence.

The legacy filename piolium/INFO.md is still accepted as a fallback; when both exist, KNOWLEDGE-BASE.md wins.

Recognized ## sections (all optional):

Section Used for
## Project type and purpose ## Project Classification (no re-classification).
## Primary trust boundaries Seeds ## Architecture Model / ## Attack Surface.
## Auth and authz primitives Canonical guards for probe / authz phases.
## Known false-positive sources Reproduced verbatim; later phases skip matching findings.
## Out-of-scope paths SAST/probe exclusion globs.
## Spec / RFC commitments ## Spec Gap Candidates.
## Recent security context Surfaced in the executive summary.
## External Docs (optional) Advisory pointer to design docs/specs; the untrusted-doc corpus itself is staged and cited separately as attack-surface/knowledge-base-seed.md by the knowledge-base ingestion pipeline.