Hermes Security Audit

IDENTITY: Auditor.SecurityAssessor. Perform layered security audit across filesystem permissions, secrets, network exposure, code patterns, dependencies, sessions, and processes — output structured CRITICAL/HIGH/MEDIUM/LOW findings with fix commands. Law: NeverSkipRotatingExposedKeys — assume compromised if plaintext keys found. WHENUSE: FirstSetup|PeriodicReview{quarterly}|BeforeNetworkExposure|AfterNewPluginOrIntegration|SuspectedCredentialLeak|ComplianceReview. ESPECIALLY:ArchiveHasActiveKeys|WorldReadableEnvFiles|GatewayOn0.0.0.0. NoSkip:ImmediateRemediation{fixPerms,changeBind,rotateKeys}. REDFLAGS: env0644->chmod600|RealKeysInArchive->RotateAndDelete|HERMES_WEBUI_HOST=0.0.0.0->ChangeTo127.0.0.1|execOrPickleInCode->AuditReplace|GitHistoryHasOldSecrets->BFGRepoCleanerThenRotate|PostgreSQLExposed->listen_addresses=localhost. RATIONALIZATIONS: NoTLSForLocalhost->AcceptableSingleUser|DotEnvFilesIfEncrypted->FileVaultOK|ExternalBindingWithFirewall->DocumentExceptionOnly. QUICKREF: Inventory{MapDirs+Processes+Listeners}->PermissionAudit{env=600,git=700}->SecretsDetect{RealKeysVsPlaceholders,GitHistory}->NetworkExposure{GatewayPort,WebUIHost,PostgreSQL}->CodePatterns{exec,pickle,shell=True,yaml.load}->CookieSession{httponly,samesite,secure,TTL}->CSRFCORS{Dependencies{npmAudit,safety,bandit,gitleaks}}->ProcessPrivileges{NoRoot}->Report{Structured{CRITICAL->HIGH->MEDIUM->LOW->INFO}}->Remediation{Immediate24h->ShortTerm1Week->MediumTerm1Month->Ongoing}.

Systematic vulnerability assessment for Hermes personal agent installations. Audits secrets management, file permissions, network exposure, code security, dependencies, and operational practices.

When to Use

Use this skill when:

• Setting up Hermes for the first time
• Periodically reviewing your Hermes installation for security gaps
• Before exposing Hermes services to a network
• After adding new integrations or plugins
• When you suspect a credential leak
• Compliance or personal security hygiene review

Do NOT use for:

• Deep code review of specific plugins (use targeted security skills instead)
• Network penetration testing of external services
• Supply chain audit of upstream dependencies (use dependency-specific skills)

Prerequisites

• macOS or Linux system with Hermes installed
• Terminal access with ability to run lsof, ps, chmod, grep
• User has read access to all Hermes directories
• Optional: gitleaks, bandit, safety, npm audit installed for deeper scanning

Methodology

The audit follows a layered approach:

1. Inventory & Discovery

Map all Hermes-related directories and running processes:

• Core Hermes home: ~/.hermes/
• Web UIs: ~/hermes-webui/, ~/hermes-workspace/
• Vault: ~/Hermes Vault/ (or custom path)
• Active processes: ps aux | grep hermes
• Network listeners: lsof -i -n -P

2. File Permission Audit

Check that sensitive files are not world-readable:

# Files to check (must be 600 or 400)
~/.hermes/archive/.env
hermes-webui/.env
hermes-workspace/.env

# Git directories must not be world-readable
~/.hermes/.git
hermes-webui/.git
hermes-workspace/.git

Expected: All 600 (owner read/write only). Anything 644 or looser is a finding.

3. Secrets Detection

Scan for live credentials in .env files and source code:

• .env → check for real values vs placeholders
• Search patterns: API_KEY, TOKEN, SECRET, PASSWORD, *_KEY, *_TOKEN
• Verify no API keys are committed to git history

Critical finding: Active API keys in plaintext files, especially in shared or archive directories.

4. Network Exposure Analysis

Determine what ports/sockets Hermes components bind to:

Gateway (hermes-cli gateway run):

• Check if using TCP port (usually 8642) or Unix socket only
• Run: lsof -i :8642 to see binding address
• Secure: Unix socket only (/tmp/hermes_rpc_*.sock) with 0600 perms
• Insecure: 0.0.0.0:8642 or 127.0.0.1:8642 — visible to network/local processes

Web UI (hermes-webui):

• Check HERMES_WEBUI_HOST env var
• If 0.0.0.0 → exposed on all interfaces
• If 127.0.0.1 → localhost only (secure)
• Verify with lsof -i :8787

Workspace:

• Check HERMES_API_URL — typically http://127.0.0.1:8642
• Ensure no HTTPS mismatch warnings in browser console

PostgreSQL (if used):

• Must bind to 127.0.0.1:5432 or Unix socket
• Never 0.0.0.0 or external IP

5. Code Security Review

Scan Python/JS code for risky patterns (use grep or bandit):

6. Cookie & Session Security

Review api/auth.py (or equivalent) for session handling:

• httponly=True — prevents JavaScript access ✓
• samesite=Lax or Strict — CSRF mitigation ✓
• secure=True — only send over HTTPS critical for production
• Session TTL reasonable (not infinite)

Check: If webUI runs over HTTP, secure flag will be conditionally false. Acceptable for localhost-only development. For network access, HTTPS required.

7. CSRF & CORS

• CSRF: Verify origin check on POST requests (_check_csrf() in webUI)
• CORS: Should be restrictive (specific origins) or disabled for local-only use

8. Dependency Vulnerability Scan

Run these tools:

Python:

pip install safety
safety check --file ~/.hermes/hermes-agent/requirements.txt

Node.js:

cd hermes-workspace
npm audit --audit-level=moderate

Also consider:

• bandit -r hermes-webui/api/ (Python SAST)
• gitleaks detect --source=hermes-webui
• gitleaks detect --source=hermes-workspace

Known vulnerable packages to watch (examples):

• debug < 2.6.9
• lodash < 4.17.21
• jsonwebtoken < 8.5.1
• marked (XSS in certain versions)

9. Secrets Sprawl Check

Count .env files across project — too many increases risk of accidental exposure. Prefer:

• Single .env at project root (gitignored)
• Or use OS keychain / secret manager
• Archive directories should NOT contain active credentials

10. Process & Service Privileges

Verify no Hermes services run as root:

ps aux | grep -E 'hermes|postgres|python.*hermes'

All should run as regular user (<user> in your case).

11. Firewall & System Hardening

• macOS: Enable Application Firewall (System Preferences → Security → Firewall)
• Consider pfctl rules to restrict inbound connections to port 8787 if webUI exposed
• SSH: Ensure PasswordAuthentication no, PermitRootLogin no

Output Format

The skill returns a structured report with:

=== HERMES SECURITY AUDIT ===

[CRITICAL] Real API keys exposed in plaintext
  Location: ~/.hermes/archive/.env
  Keys found: OPENROUTER_API_KEY, GITHUB_TOKEN
  Action: Rotate immediately; move to keychain

[HIGH] World-readable .env files
  Files: hermes-webui/.env (0644), hermes-workspace/.env (0644)
  Risk: Any local user can read configuration
  Fix: chmod 600 .env

[MEDIUM] No TLS/HTTPS configured
  Components: gateway (HTTP), webUI (HTTP)
  Risk: Traffic sniffable on localhost
  Fix: Add reverse proxy with TLS (nginx/Caddy) or enable gateway TLS

[LOW] Git directories world-readable (0o755)
  Repos: hermes-webui/.git, hermes-workspace/.git
  Risk: Commit history (including past secrets) visible
  Fix: chmod -R o-r .git

[INFO] Gateway uses Unix sockets only — no network port exposed (GOOD)

[RECOMMENDATION] Install security toolchain:
  brew install gitleaks
  pip install bandit safety
  cd hermes-workspace && npm audit

Runtime Security Layer

This skill covers pre-deploy and periodic security. For runtime security (scanning tool calls, outputs, and inbound messages at execution time), see hermes-runtime-security — it builds a Hermes plugin that hooks into pre_tool_call, post_tool_call, and pre_gateway_dispatch to automatically block dangerous commands, scan for injection, and maintain an audit trail. The two layers are complementary:

Common Findings & Fixes

Most Frequent Issues

1. .env with 0644 permissions
   Cause: umask 022 default or cp preserves perms
   Fix: chmod 600 .env and add to shell profile: umask 077

2. Real API keys in archive/
   Cause: Backup/archive directory not gitignored or encrypted
   Fix: Delete keys from disk; use security add-generic-password (macOS keychain)
   Or migrate to ~/.config/nim/env.sh sourced at login (not stored in files)

3. HERMES_WEBUI_HOST=0.0.0.0
   Cause: Default config allows remote access
   Fix: Change to 127.0.0.1 unless external access required
   If external access needed → set up SSH tunnel or TLS reverse proxy with auth

4. No npm audit / safety
   Cause: Security tooling not installed
   Fix: Add to dev dependencies or global tools; integrate into pre-commit

5. exec() or pickle in code
   Cause: Convenience over security
   Fix: Audit each usage; replace with safer alternatives (subprocess with shell=False, JSON)

6. Git history contains old secrets
   Cause: Previously committed keys not purged
   Fix: Use git filter-branch or BFG Repo-Cleaner to purge; then rotate keys

7. PostgreSQL exposed
   Cause: pg_hba.conf allows non-localhost
   Fix: Ensure listen_addresses = 'localhost' and host all all 127.0.0.1/32 md5

Remediation Workflow

After audit, create a remediation ticket with:

1. Immediate (within 24h):

   • Fix file perms on .env and .git
   • Change webUI bind address
   • Rotate any exposed keys (assume compromised)

2. Short-term (within 1 week):

   • Install security tools; run full scans
   • Review and fix all exec() / pickle usages
   • Set up gitleaks pre-commit hook
   • Add umask 077 to shell profile

3. Medium-term (within 1 month):

   • Deploy TLS for all HTTP components (use Let's Encrypt if internet-facing)
   • Migrate secrets to OS keychain or HashiCorp Vault
   • Enable macOS firewall with Hermes exceptions
   • Create automated daily security scan script

4. Ongoing:

   • Weekly npm audit / safety check
   • Monthly dependency updates
   • Quarterly full security audit (re-run this skill)

Integration with Hermes Workflow

Runtime Security Layer

This skill covers STATIC audit (permissions, secrets on disk, network exposure, code patterns). For RUNTIME security during agent operation (command scanning, injection defense, output scanning, audit trail), see:

• hermes-plugin-dev — Plugin development pattern, including the hermes-katana integration bridge
• Hermes Katana plugin at ~/.hermes/profiles/senna/plugins/katana/ — auto-scans tool calls at runtime
• Katana audit log at ~/.hermes/logs/katana-audit.jsonl — hash-chained JSONL trail

These layers complement each other: this skill audits before/during setup; Katana protects during runtime.

Related Skills

• team-wiki/setup — Document findings in Team-Wiki under Security/
• gbrain-obsidian-integration — Sync audit results to vault
• obsidian — Create security review note from output

Save audit results as: Hermes Vault/Hermes/Operations/Security/audit-YYYY-MM-DD.md

Exceptions & Caveats

Acceptable trade-offs (document reasons):

• HERMES_WEBUI_HOST=0.0.0.0 if: isolated network, behind VPN, temporary dev use
• No TLS if: strictly localhost-only, air-gapped machine, threat model excludes local sniffing
• .env files if: directory encrypted (FileVault), limited user accounts, short-lived keys

When to bring in team agents:

• Need formal risk assessment → security agent profile
• Requires compliance mapping (SOC2, ISO27001) → security or architect
• Supply chain compromise investigation → researcher + security

References

• OWASP Top 10 (2021)
• CIS Benchmarks — Local Security
• Hermes Architecture Docs (vault)
• man chmod, man sshd_config (system hardening)

Change Log

• 2026-04-25 — Initial version, based on first full-system audit of the Hermes installation