Linux Security Guardian

Linux Security Guardian

⚡ SSH MCP — REQUIRED DEPENDENCY

SSH MCP is a hard dependency. The agent MUST have SSH MCP tools available to operate. No local/legacy fallback. All operations go through SSH MCP.

Prerequisite

# SSH MCP server must be running and accessible
dependency: ssh_mcp
status: required    # if unavailable → ABORT, alert owner

Server Profile Config

Each target server needs a saved connection in SSH MCP database. Configure in SERVER_PROFILE.md:

ssh_mcp:
  connection_id: ""   # Saved connection ID, Name, or Alias
  # OR inline config:
  # host: ""
  # port: 22
  # username: ""
  # key_path: ""

Audit Modules

All 26 modules execute commands via SSH MCP. Each module file lists commands that get wrapped with ssh_exec(op="run", sessionId, command):

module command → ssh_exec(op="run", sessionId, command="module command")
              → ssh_exec(op="logs", commandId=cmdId)
              → parse output

CVE Scan

The external CVE scan runs locally (on the guardian host) using curl to CISA KEV, OSV.dev, and NVD API. Usage requires --client and --server to write results to per-server paths:

bash cve/cve-scan.sh --client "client-1" --server "server-01"

# Writes results to:
#   cve///scan-results/YYYY-MM-DD.md
#   cve///advisories/.md

Steps:

# 1. SSH MCP: ssh_exec(op="run", sessionId, command="dpkg-query -W ...") → save locally
# 2. Read from cve///scan-results/installed-packages.txt
# 3. curl CISA KEV → filter Linux entries → write advisories
# 4. curl POST OSV.dev batch → match packages → write advisories
# 5. curl NVD API (optional) → cross-check → write advisories

---

Core-Extra Config System

All owner-specific data lives in core-extra/config/ — never hardcoded in hooks or modules.

Profile

How Agents Use It

At session start → load core-extra/config/profile.md
→ Owner.name  → used in SOUL.md [WORKSPACE OWNER]
→ Email.noreply → used as from: in mail-sender.md
→ Domain.primary → used in config generation

To change: edit core-extra/config/profile.md only.

Rule

• NO hardcoded names, domains, or emails in hooks/, modules/, or root files
• All personal/owner data comes from core-extra/config/profile.md
• The core-extra directory is part of the skill (published to ClawHub with placeholders)
• Owner fills profile.md ONCE after install

---

Multi-Client Architecture

The guardian manages multiple clients, each with their own server fleet. SERVER_PROFILE.md defines ## Client: sections. The audit iterates ALL.

SERVER_PROFILE.md
├── ## Client: client-1 (7 servers)
│   ├── server-01
│   ├── server-02
│   └── ... server-07
├── ## Client: client-2 (N servers) ← add as needed
│   └── ...
└── ## Client: [NEXT-CLIENT]

All paths use // prefix:

• Findings: audit/results////
• Actions: actions///auto-done/
• CVEs: cve///advisories/
• Reports: reports///daily/

---

Purpose

Agent manages complete Linux server security autonomously via SSH MCP. Every night at 1 AM IST:

• Iterates all clients → all servers
• Full security audit runs via SSH MCP
• CVEs scanned against installed packages
• Auto-fixes applied for safe issues
• Critical issues queued for owner confirmation
• Per-server, per-client, and master email reports delivered

---

Action Decision Matrix

The most important thing — what agent does vs what it asks first:

---

Audit Modules

Execution rule: All commands go through ssh_exec(op="run", sessionId, command="") → ssh_exec(op="logs", commandId=cmdId). No local execution.

---

Finding Severity Levels

---

Confirmation Flow

When owner confirmation is needed:

Finding detected (requires confirm) on /
    ↓
Write to actions///pending-confirm/---.md
    ↓
Include in email report under "NEEDS YOUR DECISION" with / context
    ↓
Owner replies with: APPROVE  / DENY  / SKIP 
(Full ID format: ---, e.g. client-1-server-01-ACT-20260529-001)
    ↓
Search all actions/*/*/pending-confirm/ for the ID
    ↓
APPROVE → agent connects to / via SSH MCP → executes action → logs to history/
DENY    → action skipped, noted
SKIP    → deferred to next audit

---

Email Report Structure

Reports are sent per-server, per-client (summary), and master. All via email plugin/skill.

Per-Server Report

Subject: [Linux Guardian] / — YYYY-MM-DD | Score: N/100 | CRITICAL:N HIGH:N

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LINUX SECURITY GUARDIAN — NIGHTLY REPORT
Client:  | Server:  |  | YYYY-MM-DD 01:00 IST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

EXECUTIVE SUMMARY
Security Score: N/100 | Grade: X
Critical: N | High: N | Medium: N | Low: N
Auto-fixed: N | Pending confirm: N | Passed: N

━━ 🔴 CRITICAL (immediate action needed)
[Finding details]

━━ 🟠 HIGH
[Finding details]

━━ ⚡ AUTO-ACTIONS TAKEN (safe, non-breaking)
[What was auto-fixed]

━━ 🔑 NEEDS YOUR DECISION (reply APPROVE/DENY/SKIP )
[Pending confirmations with IDs — includes / prefix]

━━ 📦 CVE REPORT
[CVEs found by severity]

━━ 🌐 NETWORK & FIREWALL
[Port/firewall status]

━━ 🟡 MEDIUM / LOW
[Less urgent findings]

━━ 🟢 ALL PASSING
[Checks that passed]

━━ NEXT AUDIT: Tomorrow 01:00 IST

Per-Client Summary Report

Subject: [Linux Guardian]  Summary — YYYY-MM-DD | Servers: N/N | CRITICAL:N HIGH:N

Client: 
Servers audited: N of N total
Average score: N/100

| Server | Score | Critical | High | Score Grade |
|--------|-------|----------|------|-------------|
| ...    | ...   | ...      | ...  | ...         |

Cross-server patterns: [same vuln found on multiple servers]

---

Security Score Formula

score = 100
score -= (critical_count × 20)
score -= (high_count × 10)
score -= (medium_count × 3)
score -= (low_count × 1)
score = max(0, score)

Grade: 90-100 = A | 75-89 = B | 60-74 = C | < 60 = F

---

Folder Structure

linux-security-guardian/
  audit/
    modules/                     ← 01-system.md ... 26-ipv6-audit.md
    results/
      //
        critical/  high/  warning/  info/  pass/
          YYYY-MM-DD-.md  ← per-client/per-server findings

  actions/
    //
      auto-done/                 ← auto-fixed actions (logged)
        YYYY-MM-DD-.md
      pending-confirm/           ← waiting for owner
        -.md
      history/                   ← all approved/denied actions

  cve/
    cve-scan.sh                  ← external CVE scanner (takes --client --server)
    external-sources.md          ← all API URLs, query params, working examples
    .cache/                      ← shared cached API responses (6h TTL)
    //
      scan-results/              ← YYYY-MM-DD.md
      advisories/                ← .md

  reports/
    //
      daily/YYYY-MM-DD.md
      weekly/YYYY-WNN.md

  network/
    //
      firewall-snapshots/        ← YYYY-MM-DD-rules.txt
      port-scans/                ← YYYY-MM-DD.md
      proposed-changes/          ← -.md

  hooks/
    audit-runner.md              ← main 1 AM audit orchestrator (multi-client loop)
    on-critical.md               ← fires on any critical finding (with client/server)
    on-confirm-reply.md          ← processes owner APPROVE/DENY/SKIP
    pre-action.md                ← safety check before any action
    post-action.md               ← verify action succeeded
    mail-sender.md               ← uses email plugin/skill to send report

  crons/
    active/
      nightly-audit.md           ← 1 AM IST permanent
    completed/

  core-extra/
    config/
      profile.md                 ← owner name, domain, email (fill ONCE, no hardcode)
    hooks/                       ← shared hooks (mirrors hooks/ structure)
    templates/                   ← shared templates

  errors/
    raw/                         ← raw error logs

  memory/
    schema.json
    index.json

  SOUL.md                        ← soul context (multi-client aware)
  AGENT.md                       ← behavioral rules (multi-client, SSH MCP hard dep)
  SERVER_PROFILE.md               ← multi-client server details
  AUDIT_LOG.md                    ← append-only master log
  BASELINE.md                     ← expected state snapshot
  STATS.md