Skip to content

SPEC.md

Latest commit

 

History

History
56 lines (49 loc) · 3.89 KB

SPEC.md

File metadata and controls

56 lines (49 loc) · 3.89 KB
Raw

SPEC

§G GOAL

Port selected Strix v1.5.0 capabilities into Decepticon without parallel architecture.

§C CONSTRAINTS

  • Reuse Decepticon plugin, role, KG, reporting, LLM, sandbox contracts.
  • ∀ API operation, dependency finding, container → engagement-scoped + provenance-tagged.
  • API import ! parse-only; network actions remain RoE + egress-gated.
  • No second plugin manager, skill store, graph schema, UI server, or agent loop.
  • Preserve public tool/API contracts unless additive.
  • Both source projects Apache-2.0; retain notices for copied code, prefer native implementation.

§I INTERFACES

  • tool: API spec/collection import → compact JSON inventory + KG observations.
  • tool: cve_enrich_dependencies → repo-relative manifest path, chain, reachability evidence.
  • report: finding severity → demonstrated-impact ceiling + evidence level.
  • env: DECEPTICON_LLM_EXTRA_HEADERS → JSON object, optional OpenAI-compatible request headers.
  • env: DECEPTICON_LLM_DISABLE_STREAMING → opt-in non-streaming OpenAI-compatible calls.
  • runtime: dynamic container → engagement/run identity label; teardown selects matching label.

§R RESEARCH

id|topic|finding|src R1|Strix v1.5.0|Adds API spec/Postman targets, dependency reachability evidence, impact-calibrated severity, LLM compatibility controls, run labels|https://github.com/usestrix/strix/releases/tag/v1.5.0 R2|SCA baseline|cve_enrich_dependencies parses 4 manifest forms, ranks OSV/NVD/EPSS/KEV results, but lacks manifest provenance + reachability ladder|https://github.com/PurpleAILAB/Decepticon/blob/main/packages/decepticon/decepticon/tools/research/tools.py#L558-L684 R3|extension contracts|Plugins, roles, skills, middleware, KG ingesters already first-class; new features ! extend nearest contract|https://github.com/PurpleAILAB/Decepticon/tree/main/packages/decepticon-core/decepticon_core R4|license|Strix + Decepticon Apache-2.0|https://github.com/usestrix/strix/blob/v1.5.0/LICENSE

§V INVARIANTS

V1: ∀ imported API op → engagement + source provenance; import sends no network request. V2: ∀ imported API op → request execution still passes RoE + egress gates. V3: ∀ dependency finding → engagement-workspace-relative manifest path + evidence level; outside path emits no provenance path. V4: reported severity ≤ evidence ceiling: declared≤low, resolved≤medium, symbol/call-path≤high, runtime-observed≤critical; raw CVSS/EPSS/KEV remains retained. V5: header config ! JSON string map; reject Authorization, Host, Content-Length; non-streaming preserves usage + error handling. V6: ∀ dynamic container → engagement/run label; teardown filters both labels. V7: all new data survives existing serialisation, reporting, and engagement isolation paths. V8: API import accepts local OpenAPI/Postman JSON/YAML only; external $ref ⊥ resolves. V9: workload profile owned by one engagement; generated run ID labels every created dynamic container.

§T TASKS

id|status|task|cites T1|x|add OpenAPI/Postman import tool + KG adapter|V1,V2,V7,V8,I.tool T2|x|add dependency chain + reachability evidence|V3,V7,I.tool T3|x|cap report severity by impact evidence|V4,V7,I.report T4|x|add LLM header + non-streaming controls|V5,I.env T5|x|label dynamic containers by run|V6,I.runtime T6|x|test imported capabilities + regression paths|V1,V2,V3,V4,V5,V6,V7

§B BUGS

id|date|cause|fix B1|2026-08-09|uv run pytest timeout before collection|retry direct venv pytest; no code invariant B2|2026-08-09|dependency-evidence test skipped helper call|invoke _dependency_chains before assertion B3|2026-08-09|test expected raw CVSS, not KEV-adjusted score|assert existing composite score B4|2026-08-09|async cleanup test asserted before unrelated start completed|wait for seeded workload starts B5|2026-08-09|new imports violated repository ordering|apply ruff import ordering B6|2026-08-09|new Python files missed repository formatter|apply ruff format before CI