# Change a setting\ncerno config reset # Reset to defaults (creates backup)\n```\n\n**Proxychains4 proxy settings:**\n```bash\ncerno config set proxychains_enabled true # Enable proxy routing (default: false)\ncerno config set proxychains_host 127.0.0.1 # SOCKS5 proxy host\ncerno config set proxychains_port 9000 # SOCKS5 proxy port (matches ssh -D default)\n```\n\n\n ![\"Output](\"docs/images/default-config-values.png\")
\n
\n Show all configuration values using \"cerno config show\"\n
\n\n---\n\n## Features\n\n### π Interactive TUI for browsing/reviewing vulnerability findings\n\n*Triage hundreds of findings fast β see what matters without scrolling through raw Nessus exports.*\n\nRich tables with paged views, keyboard-driven navigation, and real-time filtering.\n\n\n ![\"Finding](\"docs/images/finding-browser.png\")
\n
\n Browse findings with paged tables and comprehensive keyboard shortcuts\n
\n\n**Key capabilities:**\n- Browse by severity, preview plugin details, clipboard copy\n- Grouped view (`host:port,port`) or raw file view\n- Multi-select operations, reversible review states\n\n---\n\n### π Intelligence & Research\n\n*Go from a finding to an exploitation path without context-switching β CVEs, Metasploit modules, and host overlap in one place.*\n\nExtract CVEs, search Metasploit modules, and compare findings across hosts.\n\n\n ![\"Plugin](\"docs/images/plugin-detail.png\")
\n
\n View plugin details with Metasploit module availability and metadata\n
\n\n**Features:**\n- **CVE extraction** - CVEs imported from .nessus file (press `[E]`)\n- **Metasploit search** - Find relevant modules by CVE/description\n- **Workflow mappings** - Plugin-specific verification/exploitation steps (press `[W]`)\n- **Host comparison** - Compare findings across hosts to find identical combinations and superset relationships\n\n\n ![\"Host](\"docs/images/host-comparison.png\")
\n
\n Compare findings to identify identical host:port combinations across plugins\n
\n\n\n ![\"Superset](\"docs/images/superset-analysis.png\")
\n
\n Analyze superset relationships to find which findings cover others\n
\n\n---\n\n### π€ Claude Assistant\n\n*Get a second opinion on exploitability without leaving your review or copying scan data elsewhere.*\n\nAsk Claude questions about findings without leaving the TUI. Powered by the `claude` CLI (`claude -p`) β no API key required, no data sent to external services beyond what `claude` itself handles.\n\n**Three scopes:**\n- **Finding level** β press `[A]` inside a finding detail view to discuss that specific plugin: CVEs, CVSS context, exploitability, verification steps\n- **Severity menu** β press `[A]` at the severity selection screen to discuss all findings across the selected scan(s)\n- **Findings list** β press `[A]` in the findings list footer to discuss the current set of findings (respects any active severity, name, or group filter)\n\n**Conversation persistence:** History is saved per-scope in SQLite and resumed automatically on re-entry. Press `C` inside the chat to clear history for the current scope.\n\n**Setup:**\n```bash\n# Install Claude Code CLI (required)\nnpm install -g @anthropic-ai/claude-code # or follow https://claude.ai/code\n\n# Opt in (off by default). You can also just press [A] in review and confirm the prompt.\ncerno config set claude_assistant_enabled true\n```\n\n**Opt-in (default off):** the assistant sends finding names, plugin metadata, affected hosts, ports, CVEs, workflow steps, and Nessus plugin output to the local `claude` CLI. Because that is sensitive engagement data, it is disabled by default. The first time you press `[A]` with `claude` installed, Cerno shows a data-path disclosure and, on confirmation, enables and remembers the choice. Enable it only if your engagement rules allow that data path.\n\n**Tool availability:** `[A]` is hidden only when `claude` is not on PATH. When installed but not yet enabled, `[A]` is shown and triggers the one-time opt-in prompt.\n\n> **Note:** Responses may be inaccurate β always verify before acting on suggestions.\n\n---\n\n### π NetExec Database Integration\n\n*Instantly see where your credentials already work, so you prioritize provable risk over theoretical findings.*\n\nAutomatically enrich finding displays with data from your NetExec databasesβsee which credentials work on affected hosts, share access, and security misconfigurations.\n\n**Features:**\n- **Credential correlation** - Shows which NetExec-discovered credentials have access to affected hosts\n- **Share access** - Displays SMB share read/write permissions across hosts\n- **Security flags** - Highlights SMB signing disabled, Zerologon, PetitPotam vulnerabilities\n- **Per-host breakdown** - Press `[N]` in finding view for detailed per-host NetExec context\n\n**Configuration:**\n```bash\n# NetExec workspace auto-detected at ~/.nxc/workspaces/default/\ncerno config set nxc_workspace_path ~/.nxc/workspaces/client_a # Custom workspace\ncerno config set nxc_enrichment_enabled false # Disable feature\n```\n\n**Supported protocols:** SMB, SSH, LDAP, MSSQL, RDP, WinRM, FTP, NFS, VNC, WMI\n\n> **Note:** NetExec databases are read in read-only mode; Cerno never modifies them.\n\n---\n\n### β‘ One-command tool launches\n\n*Skip retyping targets β launch the right tool against the exact hosts and ports of a finding.*\n\nLaunch nmap NSE scripts, NetExec, Metasploit, or custom commands with placeholder substitution.\n\n\n ![\"Tool](\"docs/images/tool-orchestration.png\")
\n
\n Select tools and review generated commands before execution\n
\n\n**Features:**\n- Launch **nmap** (NSE profiles, UDP), **NetExec**, or custom commands\n- Placeholder substitution for flexible templating\n- Execution logging & artifact tracking\n\n---\n\n### πΎ SQLite-backed persistence\n\n*Never lose review progress, and see how a host's risk profile changes over time.*\n\n**Session Management:**\n- Auto-save/resume interrupted reviews\n- Finding status: Unreviewed β In Progress β Done, moved with `[M]`; the Done list's `[M]` moves findings back to Unreviewed\n- Session statistics (duration, per-severity breakdown)\n\n**Database:** SQLite-backed persistence at `~/.cerno/cerno.db` tracks scans, findings, sessions, tool executions, and artifacts. Cross-scan tracking enables host history queries. See [docs/DATABASE.md](docs/DATABASE.md) for schema details.\n\n---\n\n### π Proxychains4 Integration\n\n*Run every tool through your pivot with a single toggle β no per-command proxy fiddling.*\n\nRoute all tool executions (nmap, NetExec, Metasploit, custom commands) through a SOCKS5 proxy via `proxychains4`. Designed for use with an SSH `-D` tunnel.\n\n**Enable in config (persists across sessions):**\n```bash\ncerno config set proxychains_enabled true\ncerno config set proxychains_host 127.0.0.1\ncerno config set proxychains_port 9000 # Matches: ssh -D 9000 user@host\n```\n\n**Or override per session:**\n```bash\ncerno review --proxy # Force-enable for this session\ncerno review --no-proxy # Force-disable for this session\n```\n\n**Behavior when active:**\n- `[PROXY]` badge (magenta) shown in the review session status line\n- proxychains4 row appears in the startup tool availability table\n- Tools run as `proxychains4 -q` (quiet) so per-connection chatter doesn't clutter the terminal; a magenta `[PROXY] proxychains4 β SOCKS5 host:port` line and a `Running via proxychains4` spinner confirm routing\n- Set `cerno config set debug_logging true` to see full proxychains4 output when troubleshooting a tunnel\n- nmap automatically adds `-Pn` and drops `sudo` when proxied (ICMP and raw sockets don't traverse SOCKS)\n- Cerno manages its own `~/.cerno/proxychains4.conf` β system config is not touched\n\n> **Requires:** `proxychains4` installed and available on PATH.\n\n---\n\n### π MCP server (BETA)\n\n*Drive an engagement from an AI client β query findings, build target lists, and generate commands programmatically.*\n\n`cerno mcp` exposes the same scan database and tooling over the Model Context Protocol, so any MCP client (Claude CLI, Claude Desktop, etc.) can work with your findings. Read-only by default; execution and mutation are opt-in. See [MCP Server (BETA)](#mcp-server-beta) below for setup and the full capability reference.\n\n---\n\n## Commands\n\n```bash\n# Import and review\ncerno import nessus # Import a single .nessus file\ncerno import nessus # Recursively import all .nessus files in a directory\ncerno review [--custom-workflows PATH] # Start interactive review\ncerno review --proxy # Force-enable proxychains4 routing for this session\ncerno review --no-proxy # Force-disable proxychains4 routing for this session\ncerno review --check # Check tool availability and exit\n\n# Manage scans\ncerno scan list # Compact summary (use --wide for all severities, --json for scripting)\ncerno scan delete \ncerno scan compare # Compare findings between two scans\ncerno scan history # View vulnerability timeline for a host\n\n# View workflows\ncerno workflow list [--custom-workflows PATH]\n\n# Configuration\ncerno config show # Display all settings with current values\ncerno config get # Get a single config value\ncerno config set # Set a config value\ncerno config reset # Reset to defaults (creates backup)\n\n# MCP server (BETA)\ncerno mcp # Serve scan data/tooling over MCP (stdio)\n\n# Maintenance\ncerno reset # Purge ~/.cerno and return to fresh state\n```\n\n---\n\n## MCP Server (BETA)\n\n`cerno mcp` exposes your scan database and tooling over the [Model Context Protocol](https://modelcontextprotocol.io),\nso any MCP client (Claude CLI, Claude Desktop, etc.) can query findings, build target lists, generate\ntool commands, and β when explicitly enabled β execute tools and update review state. It speaks over\n**stdio**, so it is launched by the client rather than run directly in a terminal.\n\n**Add it to Claude CLI:**\n\n```bash\n# pipx install (cerno is on PATH)\nclaude mcp add cerno -- cerno mcp\n\n# development / editable install (point at your checkout's venv binary)\nclaude mcp add cerno -- /abs/path/to/cerno/.venv/bin/cerno mcp\n```\n\nThen `claude mcp list` to verify, or `/mcp` inside a session to see the tools,\nresources, and prompts.\n\nThe server is **read-only by default** β execution and mutation tools stay\nhidden until you enable them:\n\n```bash\ncerno config set mcp_allow_execution true # permit execute_command\ncerno config set mcp_allow_mutations true # permit set_review_state / import_nessus\ncerno config set mcp_exec_allowlist \"nmap,nxc\" # restrict which binaries execute_command may run (\"*\" = any)\ncerno config set mcp_exec_denylist \"rm,dd,sh\" # binaries execute_command may never run (always wins)\n```\n\n> Gating flags are read once at startup; reconnect (remove + re-add, or restart the client) to apply a change.\n\n> Even with execution enabled, `execute_command` only runs binaries matching `mcp_exec_allowlist` (default: nmap, nxc, netexec, msfconsole; an empty list denies everything) and never runs binaries matching `mcp_exec_denylist` (default: destructive commands such as rm, dd, mkfs\\*, shred, shutdown). Common wrapper prefixes (`sudo`, `env`, `timeout`, `nice`, `nohup`, β¦) are unwrapped so the real target is checked. The denylist is a guardrail, not a security boundary: with `\"*\"`, shells and interpreters can still run denied programs unless you deny them too.\n\n**See [docs/MCP.md](docs/MCP.md)** for the full tool/resource/prompt reference,\nscopes, and management commands.\n\n---\n\n## Keyboard Shortcuts\n\n**In the findings list view:**\n- `[S]` - Cycle sort modes (severity, plugin ID, name, host count)\n- `[F]` - Filter findings by text (plugin name, description, etc.)\n- `[I]` - Toggle In Progress only / all statuses\n- `[C]` - Clear active text and status filters\n- `[V]` - View all unique hosts across the filtered findings\n- `[H]` - Compare: group findings by identical host:port combinations\n- `[O]` - Overlapping: find findings whose affected hosts are a superset of another's\n- `[X]` - Clear group filter (when a comparison/overlap group is active)\n- `[D]` - View full group details in pager (when a group filter is active)\n- `[E]` - Extract CVEs for all findings matching current filter\n- `[M]` - Move to next status: every filtered finding moves one step (Unreviewed β In Progress, In Progress β Done)\n- `[D]` - Done list; inside it, `[M]` moves selected findings back to Unreviewed\n- Status column: `β` Unreviewed, `β` In Progress\n- `[A]` - Ask Claude β chat about the current filtered findings set\n- `[W]` - View workflow verification steps (when available for selected finding)\n- `[N]` / `[P]` - Next / previous page\n- `[B]` - Back to severity menu\n- `[?]` - Show help menu with all available actions\n\n**In the finding detail view:**\n- `[I]` - Finding Info (plugin metadata, CVSS, CVEs)\n- `[D]` - Finding Details (host list, port distribution, plugin output)\n- `[N]` - NetExec Data (per-host credential and access breakdown)\n- `[T]` - Run Tool (launch nmap, NetExec, Metasploit, or custom workflow)\n- `[A]` - Ask Claude β chat about this specific finding\n- `[W]` - View workflow verification steps\n- `[M]` - Move to In Progress / Move to Done (label follows the finding's status)\n- `[B]` - Back to findings list\n\n---\n\n## Custom Workflows\n\nAdd plugin-specific verification workflows with `--custom-workflows` (merges & supplements with defaults) or `--custom-workflows-only` (replaces defaults):\n\n```bash\ncerno review --custom-workflows my_workflows.yaml\n```\n\n**Example workflow YAML:**\n```yaml\nversion: \"1.0\"\nworkflows:\n - plugin_id: \"57608\"\n workflow_name: \"SMB Signing Not Required\"\n steps:\n - title: \"Verify SMB signing\"\n commands: [\"netexec smb -u -p \"]\n```\n\n**Custom command placeholders:** `{TCP_IPS}`, `{UDP_IPS}`, `{TCP_HOST_PORTS}`, `{PORTS}`, `{WORKDIR}`, `{RESULTS_DIR}`, `{OABASE}`\n\n**For comprehensive documentation**, see [Custom Workflows Guide](docs/CUSTOM_WORKFLOWS.md) covering:\n- Complete YAML schema reference\n- Multi-plugin workflows\n- Placeholder system details\n- Configuration integration\n- Best practices and troubleshooting\n\n\n ![\"Custom](\"docs/images/workflow-display.png\")
\n
\n View plugin-specific verification workflows with commands and references\n
\n\n---\n\n## Troubleshooting\n\n**Database issues:**\n```bash\n# Reset database (re-import required)\nrm ~/.cerno/cerno.db\ncerno import nessus scan.nessus\n```\n\n**Config file issues:**\n```bash\n# Reset config to defaults (creates backup)\ncerno config reset\n```\n\n**Full environment reset:**\n```bash\n# Purge ~/.cerno entirely and return to a fresh installation state\ncerno reset # Prompts for typed confirmation before deleting\n```\n\n**Import failures:**\n- Ensure the `.nessus` file is valid XML (not corrupted or truncated)\n- Check file permissions and path\n- Try importing with `--verbose` for detailed output\n\n**Tool execution issues:**\n- Verify tools (nmap, netexec) are installed and on PATH\n- Check `~/.cerno/cerno.log` for detailed error messages\n\n---\n\n## Documentation\n\n- [MCP server](docs/MCP.md)\n- [Database schema & queries](docs/DATABASE.md)\n- [Adding custom tools](docs/ADDING_TOOLS_QUICKSTART.md)\n- [Tool system guide](docs/TOOL_SYSTEM_GUIDE.md)\n- [Error handling](docs/ERROR_HANDLING.md)\n\n---\n\n## Releases\n\nCerno uses **automated releases** triggered by version changes in [pyproject.toml](pyproject.toml).\n\n**How it works:**\n- When `pyproject.toml` version is updated and merged to `main`, GitHub Actions automatically:\n - Creates a git tag (e.g., `v1.0.1`)\n - Generates a GitHub Release marked as \"latest\"\n - Extracts release notes from [CHANGELOG.md](CHANGELOG.md)\n - Attaches built wheel and source distribution\n\n**View releases:** [github.com/ridgebackinfosec/cerno/releases](https://github.com/ridgebackinfosec/cerno/releases)\n\n**For contributors:** To create a new release, update the version in `pyproject.toml` and add an entry to `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/) format. The release workflow runs automatically when changes are merged to `main`.\n\n---\n\n## Contributing\n\nFound a bug or have a feature request? Please open an issue at:\n[github.com/ridgebackinfosec/cerno/issues](https://github.com/ridgebackinfosec/cerno/issues)\n\nPull requests are welcome. For major changes, please open an issue first to discuss.\n\n> **Target the `develop` branch** β all contributor PRs should be opened against `develop`, not `main`. Releases flow from `develop` to `main`.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the test workflow, and the TUI β MCP shared-core contract that keeps both interfaces working.\n\n---\n\n## About the Name\n\n**Cerno** comes from the Latin verb *cernΕ*, meaning:\n- To discern, distinguish, perceive\n- To separate, sift through\n- To decide, determine, resolve\n\nThe name reflects this tool's core purpose: **to help security professionals discern what matters** in large vulnerability scans. Just as *cernΕ* means to sift through and distinguish the important from the noise, Cerno helps you:\n\n- **Discern** which findings require immediate action vs. can be deferred\n- **Separate** findings by severity, host, and exploitability\n- **Perceive** patterns across hosts and identify verification paths\n- **Determine** the most efficient approach to vulnerability validation\n- **Resolve** findings through organized, tracked remediation workflows\n\nIn penetration testing and vulnerability management, clarity through careful examination is essentialβthat's Cerno.\n\n\n**Pronunciation:** In Classical Latin, *cerno* is pronounced **KEHR-noh** (IPA: [ΛkΙr.noΛ])βthe 'c' as a hard 'k' sound, the 'e' as in 'bed', and the 'o' as in 'no' (long). [Audio sample](https://www.howtopronounce.com/latin/cerno)\n\n---\n\n## License\n\nThis tool orchestrates local utilities and includes Nessus XML parsing functionality adapted from\n[DefensiveOrigins/NessusPluginHosts](https://github.com/DefensiveOrigins/NessusPluginHosts).\nRespect all dependencies' licenses and your organization's policies.\n"}![\"Cerno](\"docs/images/cerno-banner.png\")
\n![\"BHIS](\"https://img.youtube.com/vi/aGmRenQ28Ro/maxresdefault.jpg\")
\n\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Features](#features)\n- [Commands](#commands)\n- [MCP Server (BETA)](#mcp-server-beta)\n- [Keyboard Shortcuts](#keyboard-shortcuts)\n- [Custom Workflows](#custom-workflows)\n- [Troubleshooting](#troubleshooting)\n- [Documentation](#documentation)\n- [Releases](#releases)\n- [Contributing](#contributing)\n- [About the Name](#about-the-name)\n- [License](#license)\n\n---\n\n## Quick Start\n\n```bash\n# Install with pipx (recommended)\npipx install git+https://github.com/ridgebackinfosec/cerno.git\n\n# Import a Nessus scan\ncerno import nessus scan.nessus\n\n# Review findings interactively\ncerno review\n```\n\n**That's it!** See [Commands](#commands) for more.\n\n**No Nessus file handy?** Use the synthetic demo scan included in this repo:\n\n```bash\ncerno demo\ncerno review\n```\n\nThe demo fixture uses documentation-only IP ranges and `.example` hostnames.\nSee [docs/demo](docs/demo) for details.\n\n![\"Severity](\"docs/images/severity-selection.png\")
\n