[eugene-eko2000]

docs: add reverse-engineered CLI execution flow diagrams

Summary

Adds docs/cli-flows/, a set of Mermaid sequence diagrams that document how each snyk-agent-scan command actually executes. The CLI has grown incrementally, and there was no single place showing how responsibilities are split between client-machine I/O, flow logic and backend calls. This is documentation only: no source, test or config files are changed.

What's included

File	Covers
README.md	Index, command map, where each kind of work lives, cross-cutting findings, suggested seams
scan.md	Default command: discover, consent, inspect, redact, analyze, print
inspect.md	Same pipeline without the backend analysis step
evo.md	Mint push key, scan, revoke
help.md	Print help
guard-status.md	guard with no subcommand
guard-install.md	Deploy hook scripts, rewrite agent hook config, send test and discovery events
guard-uninstall.md	Remove hooks and scripts, revoke key
guard-discover.md	Session-start hook entry point
guard-hook-runtime.md	Installed hook script behavior per agent event (supporting, not a CLI command)
shared-subflows.md	Bootstrap, discovery, inspection and analysis sub-flows reused by the commands

Every diagram groups participants into the same four layers: User, Flow logic, Client machine resources (filesystem, env/OS, SQLite, subprocesses) and Backends (remote MCP servers, Snyk APIs, Agent Monitor). The split is visible at a glance.

Key findings (detailed in README.md)

• Two discovery engines (static tables plus AgentDiscoverer classes) run for the same agents and are merged afterwards.
• "Discovery" also spawns codesign, powershell and wsl.exe. SQLite is used only for the opencode project list.
• Command-specific behavior is encoded as command == ... checks inside shared helpers.
• evo discards the scan result, so nothing is printed. It does not revoke the key if the scan raises, and it exits 0 even when min
• Some flags do nothing: --storage-file, --checks-per-server, --no-bootstrap. --control-server is documented as never called.
• Four HTTP stacks (aiohttp, urllib, httpx, curl) with inconsistent retry policies.
• Secret redaction is applied in thr
• guard.py is a ~2100-line module that mixes several concerns.

How it was produced

Derived by reading the source at v0.6.9 (cli.py, pipelines.py, inspect.py, verify_api.py,
guard.py, agents/*, hook scripts executed.

Testing

• All 14 Mermaid diagrams (13 sequenhart in the README) were parse-checked
  with Mermaid 11. A negative test confirmed the checker rejects invalid input.
• Not yet reviewed in a rendered vie

Notes for reviewers

• These docs describe current behaviable parts, and do not propose code
  changes. The suggested seams in the README are suggestions only. - docs/README.md is not updated toay if you want that added.
• Diagrams will drift as the code changes. Worth deciding whether they should be maintained or treated as a point-in-time snapshot.

---

Note

Low Risk
Documentation-only addition with no runtime or build impact; main risk is diagram drift as the CLI evolves.

Overview
Adds docs/cli-flows/, documentation-only reverse engineering of snyk-agent-scan v0.6.9: Mermaid sequence diagrams for every CLI command (scan, inspect, evo, help, and all guard subcommands), plus shared sub-flows (bootstrap, discovery, inspection, analysis) and guard hook runtime behavior.

The index ties commands to a flowchart, maps responsibilities across User / Flow logic / Client machine / Backends, and records cross-cutting findings (dual discovery, unused flags, HTTP/retry inconsistencies, evo/guard quirks) with optional refactor seams. No application code, tests, or config change—diagrams were parse-checked with Mermaid 11.

^{Reviewed by Cursor Bugbot for commit 5cb402b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qodo-merge-etso]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can hide the parts of a finding you never read, like the evidence or the agent prompt

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-merge-etso]

PR Summary by Qodo

Document reverse-engineered CLI execution flows

📝 Documentation 🕐 40+ Minutes

AI Description

• Add Mermaid diagrams for every CLI command and the installed Guard hook runtime.
• Trace shared discovery, inspection, and analysis flows across local resources and backends.
• Record observed behavior, architectural seams, and limitations to guide future maintenance.

Diagram

sequenceDiagram
    actor User
    participant CLI as CLI dispatch
    participant Pipeline as Scan pipeline
    participant Local as Client resources
    participant MCP as MCP servers
    participant Analysis as Analysis API
    participant Guard as Guard flows
    participant Monitor as Agent Monitor
    User->>CLI: Run command
    alt scan or inspect or evo
        CLI->>Pipeline: Start flow
        Pipeline->>Local: Discover configs and skills
        opt Inspect servers
            Pipeline->>MCP: Request capabilities
        end
        opt Scan or evo
            Pipeline->>Analysis: Submit scan
        end
        Pipeline-->>CLI: Return result
    else guard command
        CLI->>Guard: Dispatch action
        Guard->>Local: Manage hooks or discover
        opt Event delivery
            Guard->>Monitor: Send hook event
        end
    end
    CLI-->>User: Output and exit

Loading

High-Level Assessment

Keep the source-derived, command-specific diagrams with shared subflows: they expose conditional behavior that a generated call graph would miss without changing runtime code. Treat the version reference as a snapshot and decide how to check these diagrams when command behavior changes.

Files changed (11) +1400 / -0

Documentation (11) +1400 / -0

README.mdIndex CLI flows and cross-cutting findings +105/-0

Index CLI flows and cross-cutting findings

• Links the command diagrams, maps responsibilities to source modules, and records findings such as duplicate discovery paths, differing HTTP transports, and suggested architectural seams.

docs/cli-flows/README.md

evo.mdTrace Evo push-key scan lifecycle +109/-0

Trace Evo push-key scan lifecycle

• Diagrams credential input, key minting, the reused scan pipeline, and revocation. Notes result presentation, failure, and exit-code behavior.

docs/cli-flows/evo.md

guard-discover.mdTrace session-start discovery and event delivery +99/-0

Trace session-start discovery and event delivery

• Documents the installed discovery hook's CLI handoff, bounded stdin and discovery work, and Agent Monitor event delivery.

docs/cli-flows/guard-discover.md

guard-hook-runtime.mdDocument installed Guard forwarder behavior +45/-0

Document installed Guard forwarder behavior

• Shows how hook scripts forward agent events to Agent Monitor without invoking the Python CLI, including their fail-open behavior.

docs/cli-flows/guard-hook-runtime.md

guard-install.mdTrace Guard installation and verification +170/-0

Trace Guard installation and verification

• Covers credential modes, per-agent config and script changes, test events, failure cleanup, and post-install discovery. Lists affected client-machine paths.

docs/cli-flows/guard-install.md

guard-status.mdDocument local Guard status checks +68/-0

Document local Guard status checks

• Shows how the status command reads user and managed hook configurations to report installed hooks without contacting a backend.

docs/cli-flows/guard-status.md

guard-uninstall.mdTrace hook removal and optional key revocation +96/-0

Trace hook removal and optional key revocation

• Documents config and script cleanup, recovery of credentials from stored hook commands, and conditions under which a push key is revoked.

docs/cli-flows/guard-uninstall.md

help.mdDocument help-command dispatch +36/-0

Document help-command dispatch

• Distinguishes the 'help' subcommand's bootstrap and banner from argparse-handled '--help' paths.

docs/cli-flows/help.md

inspect.mdTrace inspection without backend analysis +124/-0

Trace inspection without backend analysis

• Diagrams discovery, consent, MCP and skill inspection, redaction, and local output. Identifies the analysis step omitted from this command.

docs/cli-flows/inspect.md

scan.mdTrace default scan through risk presentation +180/-0

Trace default scan through risk presentation

• Documents bootstrap, discovery, consent, inspection, analysis, and output. Adds a handshake decision table and exit-code notes.

docs/cli-flows/scan.md

shared-subflows.mdDiagram reusable CLI processing stages +368/-0

Diagram reusable CLI processing stages

• Provides detailed sequence diagrams for bootstrap, two-phase discovery, sequential inspection, and analysis requests, with links for command-specific documentation.

docs/cli-flows/shared-subflows.md