vaultsovereign/vm-core

Fork 0

Files

Vault Sovereign 110d644e10 Initialize repository snapshot

2025-12-27 00:10:32 +00:00

20 KiB

Raw Blame History

VAULTMESH-OFFSEC-ENGINE.md

Civilization Ledger Security Operations Primitive

Every intrusion has a timeline. Every response has a receipt.

OffSec is VaultMesh's security operations memory — tracking real incidents, red team engagements, vulnerability discoveries, and remediation efforts with forensic-grade evidence chains.

1. Scroll Definition

Property	Value
Scroll Name	`OffSec`
JSONL Path	`receipts/offsec/offsec_events.jsonl`
Root File	`ROOT.offsec.txt`
Receipt Types	`offsec_incident`, `offsec_redteam`, `offsec_vuln_discovery`, `offsec_remediation`, `offsec_threat_intel`, `offsec_forensic_snapshot`

2. Core Concepts

2.1 Incidents

A security incident is any confirmed or suspected security event requiring investigation and response.

{
  "incident_id": "INC-2025-12-001",
  "title": "Unauthorized SSH Access Attempt on BRICK-02",
  "severity": "high",
  "status": "investigating",
  "reported_at": "2025-12-06T03:47:00Z",
  "reported_by": "guardian-automated",
  "affected_nodes": ["did:vm:node:brick-02"],
  "attack_vector": "brute_force",
  "indicators": [
    {
      "type": "ip",
      "value": "185.220.101.42",
      "context": "source of SSH attempts"
    },
    {
      "type": "pattern",
      "value": "1200+ failed auth in 10min",
      "context": "rate anomaly"
    }
  ],
  "containment_actions": [],
  "tags": ["ssh", "brute-force", "external"]
}

Severity levels:

critical — active breach, data exfiltration, system compromise
high — confirmed attack, potential breach
medium — suspicious activity, policy violation
low — anomaly, informational

Status flow:

reported → triaging → investigating → contained → eradicating → recovered → closed
                   ↘ false_positive → closed

2.2 Red Team Engagements

Authorized offensive operations against VaultMesh infrastructure.

{
  "engagement_id": "RT-2025-Q4-001",
  "title": "Q4 External Perimeter Assessment",
  "engagement_type": "external_pentest",
  "status": "in_progress",
  "scope": {
    "in_scope": ["*.vaultmesh.io", "portal-01", "brick-01", "brick-02"],
    "out_of_scope": ["production databases", "third-party integrations"],
    "rules_of_engagement": "No DoS, no social engineering, business hours only"
  },
  "team": ["operator-alpha", "operator-bravo"],
  "authorized_by": "did:vm:node:portal-01",
  "started_at": "2025-12-01T09:00:00Z",
  "scheduled_end": "2025-12-15T18:00:00Z",
  "findings": []
}

Engagement types:

external_pentest — outside-in assessment
internal_pentest — assumed-breach scenario
red_team — full adversary emulation
purple_team — collaborative attack/defense
tabletop — scenario-based discussion (no actual attacks)

2.3 Vulnerability Discoveries

Vulnerabilities found through any means (scanning, manual testing, bug reports, threat intel).

{
  "vuln_id": "VULN-2025-12-001",
  "title": "OpenSSH CVE-2024-XXXXX on BRICK-02",
  "severity": "high",
  "cvss_score": 8.1,
  "status": "confirmed",
  "discovered_at": "2025-12-06T10:30:00Z",
  "discovered_by": "RT-2025-Q4-001",
  "discovery_method": "pentest",
  "affected_assets": ["did:vm:node:brick-02"],
  "cve": "CVE-2024-XXXXX",
  "description": "Remote code execution via crafted SSH packet",
  "evidence_path": "cases/offsec/VULN-2025-12-001/evidence/",
  "remediation_status": "pending",
  "tags": ["ssh", "rce", "cve"]
}

2.4 Remediations

Actions taken to fix vulnerabilities or recover from incidents.

{
  "remediation_id": "REM-2025-12-001",
  "title": "Patch OpenSSH on BRICK-02",
  "related_to": {
    "type": "vulnerability",
    "id": "VULN-2025-12-001"
  },
  "status": "completed",
  "assigned_to": "sovereign",
  "started_at": "2025-12-06T11:00:00Z",
  "completed_at": "2025-12-06T11:45:00Z",
  "actions_taken": [
    "Applied OpenSSH 9.6p1 patch",
    "Restarted sshd service",
    "Verified patch version",
    "Re-scanned to confirm fix"
  ],
  "verification": {
    "method": "rescan",
    "result": "not_vulnerable",
    "verified_at": "2025-12-06T12:00:00Z"
  },
  "evidence_path": "cases/offsec/REM-2025-12-001/evidence/"
}

3. Mapping to Eternal Pattern

3.1 Experience Layer (L1)

CLI (vm-offsec):

# Incident management
vm-offsec incident create --title "Suspicious outbound traffic" --severity medium
vm-offsec incident list --status investigating
vm-offsec incident show INC-2025-12-001
vm-offsec incident update INC-2025-12-001 --status contained
vm-offsec incident close INC-2025-12-001 --resolution "false_positive"

# Red team
vm-offsec redteam create --config engagements/q4-external.json
vm-offsec redteam list --status in_progress
vm-offsec redteam finding add RT-2025-Q4-001 --vuln VULN-2025-12-001
vm-offsec redteam close RT-2025-Q4-001 --report reports/RT-2025-Q4-001.pdf

# Vulnerabilities
vm-offsec vuln create --title "Weak TLS config" --severity medium --asset portal-01
vm-offsec vuln list --status confirmed --severity high,critical
vm-offsec vuln remediate VULN-2025-12-001 --assigned sovereign

# Threat intel
vm-offsec intel add --type ioc --value "185.220.101.42" --context "Tor exit node"
vm-offsec intel search --type ip --value "185.220.101.42"

# Forensics
vm-offsec forensic snapshot --node brick-02 --reason "INC-2025-12-001 investigation"
vm-offsec forensic timeline INC-2025-12-001 --output timeline.json

MCP Tools:

offsec_incident_create — create new incident
offsec_incident_status — get incident details
offsec_vuln_search — search vulnerabilities
offsec_ioc_check — check if indicator is known
offsec_timeline — generate incident timeline

Portal HTTP:

POST /offsec/incidents — create incident
GET /offsec/incidents — list incidents
GET /offsec/incidents/{id} — incident details
PATCH /offsec/incidents/{id} — update incident
POST /offsec/redteam — create engagement
GET /offsec/vulnerabilities — list vulns
POST /offsec/intel — add threat intel
POST /offsec/forensic/snapshot — capture forensic state

3.2 Engine Layer (L2)

Step 1 — Plan → `offsec_case_contract.json`

For incidents and red team engagements, an explicit case contract:

Incident Contract:

{
  "case_id": "INC-2025-12-001",
  "case_type": "incident",
  "title": "Unauthorized SSH Access Attempt on BRICK-02",
  "severity": "high",
  "created_at": "2025-12-06T03:47:00Z",
  "phases": [
    {
      "phase_id": "phase-1-triage",
      "name": "Triage",
      "objectives": [
        "Confirm attack is real (not false positive)",
        "Identify affected systems",
        "Assess immediate risk"
      ],
      "checklist": [
        "Review Guardian alerts",
        "Check auth logs on BRICK-02",
        "Correlate with other nodes",
        "Determine if access was successful"
      ]
    },
    {
      "phase_id": "phase-2-contain",
      "name": "Containment",
      "objectives": [
        "Stop ongoing attack",
        "Prevent lateral movement",
        "Preserve evidence"
      ],
      "checklist": [
        "Block source IP at firewall",
        "Rotate SSH keys if needed",
        "Snapshot affected systems",
        "Enable enhanced logging"
      ]
    },
    {
      "phase_id": "phase-3-eradicate",
      "name": "Eradication",
      "objectives": [
        "Remove attacker access",
        "Patch vulnerabilities",
        "Harden configuration"
      ]
    },
    {
      "phase_id": "phase-4-recover",
      "name": "Recovery",
      "objectives": [
        "Restore normal operations",
        "Verify security posture",
        "Document lessons learned"
      ]
    }
  ],
  "assigned_responders": ["sovereign"],
  "escalation_path": ["guardian-automated", "portal-admin"]
}

Red Team Contract:

{
  "case_id": "RT-2025-Q4-001",
  "case_type": "redteam",
  "title": "Q4 External Perimeter Assessment",
  "engagement_type": "external_pentest",
  "created_at": "2025-12-01T09:00:00Z",
  "phases": [
    {
      "phase_id": "phase-1-recon",
      "name": "Reconnaissance",
      "objectives": ["Map external attack surface", "Identify services", "OSINT gathering"]
    },
    {
      "phase_id": "phase-2-enum",
      "name": "Enumeration",
      "objectives": ["Service fingerprinting", "Version detection", "Vuln scanning"]
    },
    {
      "phase_id": "phase-3-exploit",
      "name": "Exploitation",
      "objectives": ["Attempt exploitation of discovered vulns", "Document success/failure"]
    },
    {
      "phase_id": "phase-4-report",
      "name": "Reporting",
      "objectives": ["Compile findings", "Risk rating", "Remediation recommendations"]
    }
  ],
  "scope": { "...": "..." },
  "rules_of_engagement": "...",
  "authorized_by": "did:vm:node:portal-01"
}

Step 2 — Execute → `offsec_case_state.json`

{
  "case_id": "INC-2025-12-001",
  "case_type": "incident",
  "status": "contained",
  "created_at": "2025-12-06T03:47:00Z",
  "updated_at": "2025-12-06T06:30:00Z",
  "phases": [
    {
      "phase_id": "phase-1-triage",
      "status": "completed",
      "started_at": "2025-12-06T03:50:00Z",
      "completed_at": "2025-12-06T04:15:00Z",
      "findings": [
        "Attack confirmed real - 1247 failed SSH attempts from 185.220.101.42",
        "No successful authentication detected",
        "Only BRICK-02 targeted"
      ],
      "evidence": ["logs/brick-02-auth.log.gz", "screenshots/guardian-alert.png"]
    },
    {
      "phase_id": "phase-2-contain",
      "status": "completed",
      "started_at": "2025-12-06T04:15:00Z",
      "completed_at": "2025-12-06T04:30:00Z",
      "actions_taken": [
        "Blocked 185.220.101.42 at WireGuard firewall",
        "Verified no unauthorized sessions active",
        "Captured forensic snapshot of BRICK-02"
      ],
      "evidence": ["firewall-rule-add.sh", "snapshot-brick02-20251206.tar.gz"]
    },
    {
      "phase_id": "phase-3-eradicate",
      "status": "in_progress",
      "started_at": "2025-12-06T06:00:00Z"
    },
    {
      "phase_id": "phase-4-recover",
      "status": "pending"
    }
  ],
  "indicators_collected": [
    {"type": "ip", "value": "185.220.101.42"},
    {"type": "user_agent", "value": "SSH-2.0-libssh_0.9.6"}
  ],
  "timeline_path": "cases/offsec/INC-2025-12-001/timeline.json"
}

Step 3 — Seal → Receipts

Incident Receipt (on case closure):

{
  "type": "offsec_incident",
  "incident_id": "INC-2025-12-001",
  "title": "Unauthorized SSH Access Attempt on BRICK-02",
  "severity": "high",
  "timestamp_reported": "2025-12-06T03:47:00Z",
  "timestamp_closed": "2025-12-06T12:00:00Z",
  "status": "closed",
  "resolution": "contained_no_breach",
  "affected_nodes": ["did:vm:node:brick-02"],
  "attack_vector": "brute_force",
  "phases_completed": 4,
  "indicators_count": 2,
  "evidence_manifest": "cases/offsec/INC-2025-12-001/EVIDENCE.sha256",
  "timeline_hash": "blake3:aaa111...",
  "lessons_learned": "Implement fail2ban on all nodes; add SSH rate limiting at network edge",
  "tags": ["incident", "ssh", "brute-force", "contained"],
  "root_hash": "blake3:bbb222...",
  "proof_path": "cases/offsec/INC-2025-12-001/PROOF.json"
}

Vulnerability Discovery Receipt:

{
  "type": "offsec_vuln_discovery",
  "vuln_id": "VULN-2025-12-001",
  "title": "OpenSSH CVE-2024-XXXXX on BRICK-02",
  "severity": "high",
  "cvss_score": 8.1,
  "timestamp_discovered": "2025-12-06T10:30:00Z",
  "discovered_by": "RT-2025-Q4-001",
  "discovery_method": "pentest",
  "affected_assets": ["did:vm:node:brick-02"],
  "cve": "CVE-2024-XXXXX",
  "remediation_status": "remediated",
  "remediation_id": "REM-2025-12-001",
  "tags": ["vulnerability", "ssh", "rce", "cve", "remediated"],
  "root_hash": "blake3:ccc333..."
}

Remediation Receipt:

{
  "type": "offsec_remediation",
  "remediation_id": "REM-2025-12-001",
  "title": "Patch OpenSSH on BRICK-02",
  "related_vuln": "VULN-2025-12-001",
  "timestamp_started": "2025-12-06T11:00:00Z",
  "timestamp_completed": "2025-12-06T11:45:00Z",
  "status": "verified",
  "actions_count": 4,
  "verification_method": "rescan",
  "verification_result": "not_vulnerable",
  "evidence_manifest": "cases/offsec/REM-2025-12-001/EVIDENCE.sha256",
  "tags": ["remediation", "patch", "ssh", "verified"],
  "root_hash": "blake3:ddd444..."
}

Red Team Receipt (on engagement close):

{
  "type": "offsec_redteam",
  "engagement_id": "RT-2025-Q4-001",
  "title": "Q4 External Perimeter Assessment",
  "engagement_type": "external_pentest",
  "timestamp_started": "2025-12-01T09:00:00Z",
  "timestamp_closed": "2025-12-15T17:00:00Z",
  "status": "completed",
  "findings_critical": 0,
  "findings_high": 1,
  "findings_medium": 3,
  "findings_low": 7,
  "findings_info": 12,
  "vulns_created": ["VULN-2025-12-001", "VULN-2025-12-002", "VULN-2025-12-003", "VULN-2025-12-004"],
  "report_hash": "blake3:eee555...",
  "report_path": "cases/offsec/RT-2025-Q4-001/report.pdf",
  "tags": ["redteam", "pentest", "external", "q4"],
  "root_hash": "blake3:fff666...",
  "proof_path": "cases/offsec/RT-2025-Q4-001/PROOF.json"
}

3.3 Ledger Layer (L3)

Receipt Types:

Type	When Emitted
`offsec_incident`	Incident closed
`offsec_redteam`	Red team engagement closed
`offsec_vuln_discovery`	Vulnerability confirmed
`offsec_remediation`	Remediation verified
`offsec_threat_intel`	New IOC/TTP added
`offsec_forensic_snapshot`	Forensic capture taken

Merkle Coverage:

All receipts append to receipts/offsec/offsec_events.jsonl
ROOT.offsec.txt updated after each append
Guardian anchors OffSec root in anchor cycles

4. Query Interface

offsec_query_events.py:

# Incidents by status
vm-offsec query --type incident --status investigating,contained

# Incidents by severity
vm-offsec query --type incident --severity critical,high

# Vulnerabilities pending remediation
vm-offsec query --type vuln_discovery --remediation-status pending

# Red team findings
vm-offsec query --engagement RT-2025-Q4-001

# Date range
vm-offsec query --from 2025-11-01 --to 2025-12-01

# By affected node
vm-offsec query --node brick-02

# IOC search
vm-offsec query --ioc-type ip --ioc-value "185.220.101.42"

# Export for compliance
vm-offsec query --from 2025-01-01 --format csv > security_events_2025.csv

Timeline Generator:

# Generate incident timeline
vm-offsec timeline INC-2025-12-001 --format json
vm-offsec timeline INC-2025-12-001 --format mermaid > timeline.mmd

# Output (Mermaid):
# gantt
#     title INC-2025-12-001 Timeline
#     dateFormat  YYYY-MM-DDTHH:mm
#     section Triage
#     Review alerts           :2025-12-06T03:50, 15m
#     Confirm attack          :2025-12-06T04:05, 10m
#     section Containment
#     Block IP                :2025-12-06T04:15, 5m
#     Verify no breach        :2025-12-06T04:20, 10m

5. Design Gate Checklist

Question	OffSec Answer
Clear entrypoint?	✅ CLI (`vm-offsec`), MCP tools, Portal HTTP
Contract produced?	✅ `offsec_case_contract.json` for incidents and red team
State object?	✅ `offsec_case_state.json` tracking phases and evidence
Receipts emitted?	✅ Six receipt types covering all security operations
Append-only JSONL?	✅ `receipts/offsec/offsec_events.jsonl`
Merkle root?	✅ `ROOT.offsec.txt`
Guardian anchor path?	✅ OffSec root included in ProofChain
Query tool?	✅ `offsec_query_events.py` + timeline generator

6. Evidence Chain Integrity

OffSec has stricter evidence requirements than other scrolls:

6.1 Evidence Manifest

Every case produces an evidence manifest:

cases/offsec/INC-2025-12-001/
├── contract.json
├── state.json
├── timeline.json
├── EVIDENCE.sha256
├── PROOF.json
└── evidence/
    ├── logs/
    │   └── brick-02-auth.log.gz
    ├── screenshots/
    │   └── guardian-alert.png
    ├── captures/
    │   └── traffic-2025-12-06.pcap.gz
    └── forensic/
        └── snapshot-brick02-20251206.tar.gz

EVIDENCE.sha256:

blake3:aaa111...  evidence/logs/brick-02-auth.log.gz
blake3:bbb222...  evidence/screenshots/guardian-alert.png
blake3:ccc333...  evidence/captures/traffic-2025-12-06.pcap.gz
blake3:ddd444...  evidence/forensic/snapshot-brick02-20251206.tar.gz

6.2 Chain of Custody

For legal/compliance scenarios, evidence includes custody metadata:

{
  "evidence_id": "evidence/logs/brick-02-auth.log.gz",
  "collected_at": "2025-12-06T04:00:00Z",
  "collected_by": "sovereign",
  "collection_method": "scp from brick-02:/var/log/auth.log",
  "original_hash": "blake3:aaa111...",
  "custody_chain": [
    {
      "action": "collected",
      "timestamp": "2025-12-06T04:00:00Z",
      "actor": "sovereign",
      "location": "brick-02"
    },
    {
      "action": "transferred",
      "timestamp": "2025-12-06T04:05:00Z",
      "actor": "sovereign",
      "from": "brick-02",
      "to": "portal-01:/cases/offsec/INC-2025-12-001/evidence/"
    }
  ]
}

7. Integration Points

System	Integration
Guardian	Triggers incident creation on security events; OffSec can request emergency anchors
Drills	Drill findings can auto-create vulnerabilities in OffSec
Mesh	Incidents can trigger emergency capability revocations; node isolation
Treasury	Red team engagements can have associated budgets; incident costs tracked
Oracle	Can query OffSec for compliance ("Any unresolved critical vulns?")

8. Future Extensions

SOAR integration: Automated playbook execution via n8n
Threat intel feeds: Auto-import IOCs from MISP, OTX, etc.
MITRE ATT&CK mapping: Tag incidents/findings with ATT&CK techniques
SLA tracking: Time-to-contain, time-to-remediate metrics
External reporting: Generate reports for insurers, regulators, clients
AI-assisted triage: Use Oracle to help classify and prioritize incidents

9. Drills vs. OffSec: When to Use Which

Aspect	Drills	OffSec
Purpose	Practice and training	Real operations
Targets	Lab/isolated environments	Production or scoped prod
Findings	Learning outcomes	Actionable vulnerabilities
Evidence	Educational artifacts	Legal-grade evidence
Urgency	Scheduled	Real-time response
Receipts	`security_drill_run`	`offsec_incident`, `offsec_redteam`, etc.

A Drill might discover a theoretical weakness. OffSec confirms and tracks its remediation in production.

20 KiB Raw Blame History