# 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.

```json
{
  "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.

```json
{
  "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).

```json
{
  "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.

```json
{
  "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`):

```bash
# 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**:

```json
{
  "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**:

```json
{
  "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`

```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):

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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):

```json
{
  "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`:

```bash
# 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**:

```bash
# 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:

```json
{
  "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.