Evidence-driven cybersecurity reasoning engine.
AXIOM builds structured attack plans and chains from techniques that have been validated, scored, and approved through a controlled trust lifecycle. It does not guess. Every output is source-backed, evidence-floored, and auditable.
The system can think freely, but it can only act on what it can prove.
config.py — single source of truth: weights, thresholds, vocabulary
↓
core/
models.py — all Pydantic schemas and enums
db.py — SQLite, append-only evidence, named repository functions
validator.py — schema contract layer between every agent handoff
orchestration.py — neutral service layer (review/ and main.py call this, not agents/)
↓
agents/
agent1_ingest.py — firewall: normalize, validate, reject, pass to Agent 2
agent2_score.py — sole writer to techniques table; deterministic scoring
agent3_plan.py — evidence-floored planner with hard/soft constraints
agent4_chain.py — DB-backed chain builder + bounded shadow reasoning
agent5_feedback.py — evidence ingestion, rescore trigger, decay audit
review/
cli.py — human approval boundary for status promotions
main.py — thin CLI entry point
data/seed.json — curated initial technique dataset
config.py
↓
core/models.py → core/db.py → core/validator.py
↓
core/orchestration.py
↓ ↓
agents/ review/ main.py
↓
SQLite via core/db.py
Agents do not import each other. All inter-agent state transfer happens through the DB.
Techniques are identified by variant_id, not by MITRE ID. This allows platform variants of the same technique to coexist as separate rows:
| variant_id | technique_id | platform |
|---|---|---|
T1548::Linux |
T1548 |
Linux |
T1548::Windows |
T1548 |
Windows |
T1548.003::Linux |
T1548.003 |
Linux |
AXIOM-3F9A1C2B |
AXIOM-... |
Cloud |
technique_id is a queryable MITRE index, not a primary key.
The evidence table has DB-level triggers that block UPDATE and DELETE. No evidence record can ever be mutated. Confidence scores are derived from evidence, not stored as mutable state.
| Status | Meaning |
|---|---|
lab_validated |
Confirmed working via controlled execution |
source_supported |
Supported by credible sources, no lab run |
historically_validated |
Previously lab-validated, past decay threshold |
conflicted |
Contradictory evidence |
deprecated |
Confirmed non-functional, explicitly deprecated |
unverified |
No credible source support |
lab_validated requires human approval via the review queue. It is never auto-assigned.
confidence =
0.40 × execution_evidence
0.20 × source_quality
0.15 × source_consensus
0.10 × environment_match
0.10 × recency
0.05 × stability
detection_risk is a separate field. It never affects confidence.
planner_score = confidence × mission_fit × stealth_weighted_risk_adjustment
Where stealth_weighted_risk_adjustment is only applied when low_noise_preferred constraint is active.
pip install pydantic# 1. Ingest the seed technique dataset
python main.py ingest data/seed.json
# 2. Check system status
python main.py status
# 3. Generate a plan
python main.py plan --goal "privilege escalation on Linux" --os Linux
# 4. Generate a chain
python main.py chain --goal "privilege escalation" --os Linux --no-shadow
# 5. Submit execution evidence
python main.py feedback T1548.003::Linux success ubuntu-22.04 --notes "NOPASSWD confirmed"
# 6. Check for pending reviews
python main.py review list
# 7. Approve a promotion (if queued)
python main.py review approve <review_id> --reviewer yourname
# 8. Run decay audit
python main.py decay --dry-runpython main.py ingest <file.json>Loads a JSON array of technique records through Agent 1. Rejects malformed records to the error queue. Never passes invalid data forward.
python main.py feedback <variant_id> <success|failure> <environment> [--notes "..."]Submits execution evidence. Appends to the immutable evidence log. Triggers Agent 2 rescore. Queues a promotion review if evidence threshold is met.
Example:
python main.py feedback T1548.003::Linux success ubuntu-22.04 --notes "NOPASSWD for less"
python main.py feedback T1047::Windows failure windows-11-22h2 --notes "wmic.exe not found"python main.py plan --goal "..." --os <OS> [--mode strict|guided_bootstrap|research]
[--constraints <c1> <c2>] [--phases <p1> <p2>] [--max-steps N]
[--show-excluded]Modes:
strict— lab_validated techniques onlyguided_bootstrap— lab_validated + source_supported (default)research— all evidence classes, marked as hypothesis
Hard constraints (filter):
no_state_changeno_kernel_exploitno_network_trafficno_file_write
Soft constraints (ranking):
low_noise_preferredspeed_preferredminimal_dependenciesavoid_known_signatures
python main.py chain --goal "..." --os <OS> [--mode ...] [--steps N] [--no-shadow]Builds an attack logic chain. Each step is typed as confirmed, probable, or hypothesis. Gaps become validation tasks.
--no-shadow disables the Claude API call for proposal generation. Use this in offline environments or when you only want DB-backed output.
python main.py review list
python main.py review show <id>
python main.py review approve <id> --reviewer <name>
python main.py review reject <id> --reviewer <name>
python main.py review errors
python main.py review statusThe review queue is the only path to lab_validated. A human reviewer is required. Reviewer identity is recorded and cannot be null on approved records.
python main.py statusShows technique count, status breakdown, confidence average, pending reviews, and pending errors.
python main.py decay [--dry-run]Audits techniques for stale evidence. Rescores and demotes lab_validated techniques that have not been validated within the decay window (365 days).
[
{
"technique_id": "T1548.003",
"technique_name": "Abuse Elevation Control Mechanism",
"title": "Enumerate sudo permissions",
"platform": ["Linux"],
"command": "sudo -l",
"preconditions": ["interactive shell"],
"dependencies": [],
"source_refs": ["GTFOBins", "HackTricks"],
"alternatives": ["id", "getcap -r / 2>/dev/null"]
}
]Required fields: technique_name, title, platform, command, source_refs
Records missing any required field are rejected to the error queue. Empty command, empty platform, and empty source_refs are hard-rejected.
Shadow reasoning (Agent 4)
→ proposals (UNTRUSTED)
→ Agent 1 ingestion queue
→ Agent 2 scoring
→ review queue
→ human approval
→ lab_validated
Evidence (Agent 5)
→ append-only evidence log
→ Agent 2 rescore
→ review queue (if threshold met)
→ human approval
→ lab_validated
Proposals from shadow reasoning are never used directly. They must re-enter the system through Agent 1 and survive scoring and human review before any use. The parser-enforced structural split in core/validator.py makes this mechanical, not instructional.
python -m pytest tests/ -vExpected: 134 passed, 8 skipped.
The 8 skipped tests are static analysis tests that activate once all agent files are present in agents/ — they verify write authority boundaries across the codebase.
-
No scraping — Phase 2 (controlled source scraping) is not yet implemented. Ingestion is manual seed files only.
-
Pydantic V2 warnings — Models use V1
@validatorsyntax. Functional but will need migration before Pydantic V3. -
Shadow reasoning — The Agent 4 Claude API call has no retry/timeout hardening. It is non-fatal (chain continues if it fails) but should be treated as optional in production.
-
No package install — Run from the project root with
python main.py. Proper packaging (setup.py/pyproject.toml) is a v2 item. -
SQLite only — Designed to migrate to Postgres. All writes go through named repository functions in
core/db.py. No raw SQL in agents.