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
# Tools required: ssh_conn, ssh_exec
# Config reference: /save_data/projects/ssh_mcp/
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: "\x3Cid-name-or-alias-from-ssh-conn-list>"   # Saved connection ID, Name, or Alias
  # OR inline config:
  # host: "\x3Cserver-ip>"
  # port: 22
  # username: "\x3Cuser>"
  # key_path: "\x3C/path/to/key>"

Connection Lifecycle

1. ssh_conn(op="list") → find target server connection_id
   → If not found → log error, ABORT audit (no fallback)

2. ssh_exec(op="open", connectionId) → returns sessionId
   → If fails → log error, ABORT audit
   → sessionId used for ALL subsequent commands

3. Run commands in audit modules:
   → Prefer passing multiple commands in a module as a sequential array to reduce overhead: `ssh_exec(op="run", sessionId, command=["cmd1", "cmd2", ...])` → returns a single commandId.
   → Alternatively, run individually: `ssh_exec(op="run", sessionId, command="\x3Ccommand>")`.
   → If multiple command runs are triggered concurrently, the SSH MCP server's self-healing queue handles concurrency. If the target server rejects channel opens (due to low `MaxSessions`), the MCP server dynamically drops the concurrency limit, unshifts the task, and retries with backoff.
   → Retrieve output: `ssh_exec(op="logs", commandId=commandId, stream="stdout")`.

4. ssh_exec(op="close", sessionId) after audit complete

SSH MCP Tool Usage

Audit Modules

All 18 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 also goes through SSH MCP:

# 1. ssh_exec(op="run", sessionId, command="dpkg-query -W -f='${Package}	${Version}\
'") → installed packages
# 2. ssh_exec(op="run", sessionId, command="cat /etc/os-release") → OS info
# 3. ssh_exec(op="run", sessionId, command="curl -s 'https://www.cisa.gov/...'") → CISA KEV fetch from remote
# 4. ssh_exec(op="run", sessionId, command="curl -s -X POST 'https://api.osv.dev/...'") → OSV.dev query from remote
# 5. ssh_exec(op="run", sessionId, command="curl -s 'https://services.nvd.nist.gov/...'") → NVD query from remote
# Parse results locally, write advisories to cve/advisories/

Purpose

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

• Full security audit runs via SSH MCP
• CVEs scanned against installed packages
• Auto-fixes applied for safe issues
• Critical issues queued for owner confirmation
• Email report 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="\x3Ccommand>") → ssh_exec(op="logs", commandId=cmdId). No local execution.

Finding Severity Levels

Confirmation Flow

When owner confirmation is needed:

Finding detected (requires confirm)
    ↓
Write to actions/pending-confirm/\x3Cslug>.md
    ↓
Include in email report under "NEEDS YOUR DECISION"
    ↓
Owner replies with: APPROVE \x3Cslug> / DENY \x3Cslug> / SKIP \x3Cslug>
    ↓
APPROVE → agent executes action → logs to actions/history/
DENY    → action skipped, noted
SKIP    → deferred to next audit

Email Report Structure

Report is sent via email plugin/skill (not implemented inline — use available email skill).

Subject: [Linux Guardian] Server Audit — YYYY-MM-DD | CRITICAL:N HIGH:N

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LINUX SECURITY GUARDIAN — NIGHTLY REPORT
Server: \x3Chostname> | \x3CIP> | YYYY-MM-DD 01:00 IST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

EXECUTIVE SUMMARY
Security Score: N/100
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 \x3Cid>)
[Pending confirmations with IDs]

━━ 📦 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

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 | \x3C 60 = F

Folder Structure

linux-security-guardian/
  audit/
    modules/
      01-system.md ... 18-rootkit.md   ← audit module definitions
    results/
      critical/  high/  warning/  info/  pass/
        YYYY-MM-DD-\x3Ccheck>.md          ← finding entries

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

  cve/
    cve-scan.sh           ← external CVE scanner (CISA KEV + OSV.dev + NVD API)
    external-sources.md   ← all API URLs, query params, working examples
    .cache/               ← cached API responses (avoids re-fetch)
    scan-results/
      YYYY-MM-DD.md       ← full CVE scan output
    advisories/
      \x3Ccve-id>.md         ← notable CVE details w/ source attribution

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

  network/
    firewall-snapshots/
      YYYY-MM-DD-rules.txt   ← iptables/nft snapshot
    port-scans/
      YYYY-MM-DD.md
    proposed-changes/
      \x3Cid>-\x3Cchange>.md       ← firewall changes awaiting confirm

  hooks/
    audit-runner.md     ← main 1 AM audit orchestrator
    on-critical.md      ← fires on any critical finding
    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/

  memory/
    schema.json
    index.json

  SOUL.md
  AGENT.md
  SERVER_PROFILE.md    ← server details, owner config
  AUDIT_LOG.md         ← append-only master log
  BASELINE.md          ← expected state snapshot
  STATS.md