Scanner guide

agenthound scan collects the local host and any added network scope in one operation. Active verification is the default.

Targets

agenthound scan
agenthound scan ai-gateway.internal
agenthound scan 10.20.0.0/24
agenthound scan @targets.txt

A positional target adds to local collection. Without one, AgentHound seeds loopback, active local unicast interfaces, endpoints from supported MCP configuration, and standard ports for supported AI services.

A targets file accepts one hostname, IP, or CIDR per line. Blank lines and lines beginning with # are ignored. Target expansion is capped at 1,048,576 hosts, including the aggregate contents of a targets file. Multicast and link-local scope are rejected.

An invalid positional target fails before configured network enumeration begins. Explicit public targets are accepted.

Modes

Mode	Collection and actions
Active	Uses configured authentication, reuses compatible credentials, verifies MCP resource access and Streamable HTTP Origin handling, and runs eligible reversible ContextForge probes.
Active with --deep	Adds recursive instruction collection, bounded Qdrant point references, expensive probes, and bounded Ollama embedding verification.
--stealth	Performs anonymous read-only collection and exact configured authentication. Credential reuse, compute, tool invocation, and mutation are disabled.
--stealth --deep	Adds deep filesystem and payload reads while retaining stealth restrictions.

Read-only protocol operations may use POST when the protocol requires it. --insecure changes TLS certificate verification only; it does not change target exclusions or action mode.

Exclusions

--exclude accepts an exact hostname, IP, or CIDR and can be repeated:

agenthound scan 10.20.0.0/16 \
  --exclude admin.internal \
  --exclude 10.20.4.12 \
  --exclude 10.20.8.0/24

The contact policy applies before target admission and at the final socket dial. Hostnames are compared case-insensitively without a trailing DNS dot. Resolved addresses, redirects, derived management and cleanup URLs, and remote JWKS locations pass through the same policy. Mixed DNS results use only admitted addresses; a fully excluded scope produces a skipped outcome and no connection.

Configuration referring to an excluded endpoint remains useful graph evidence, but AgentHound does not enumerate that endpoint. A stdio MCP child process runs as a local process and is outside network-level enforcement.

Normalized exclusions are stored in the artifact and reused by agenthound revert.

Credentials and service collection

AgentHound stores concrete credentials as Credential.properties.value and uses value_hash for identity and deduplication. Each newly discovered raw value is printed once unless --quiet is set.

The planner can execute LiteLLM master, bearer, and API keys; Open WebUI bearer and API keys; Jupyter tokens; A2A bearer credentials; and MCP bearer credentials tied to an exact resource. Masks, hashes, unresolved environment references, unresolved secret-provider references, custom strings, and basic-auth guesses are preserved as evidence but are not presented to services.

For A2A, a bearer retry remains eligible when the bounded anonymous probe is protected or inconclusive. When both the public card and protocol probe already succeed anonymously, the planner does not repeat the same card collection with a credential.

Anonymous collection covers applicable LiteLLM, Open WebUI, Jupyter, Qdrant, MLflow, and Ollama endpoints. New targets and credentials are indexed as they appear, allowing useful authenticated work during the same scan.

Open WebUI configuration inventory requires an authorized credential. AgentHound reads the configured Ollama backends and enabled Qdrant external-knowledge connections, but never stores their backend authentication material. One successful exhaustive configuration pass completes that Open WebUI inventory and suppresses remaining credential guesses; earlier rejected guesses remain in the action journal and do not erase the successful result. A failed or truncated configuration endpoint keeps the inventory incomplete. Backend links mean “configured,” not “reachable”: AgentHound does not infer them from matching hosts or upgrade them because a separate destination probe succeeded.

Instruction integrity

AgentHound classifies collected AGENTS.md, CLAUDE.md, Cursor, Copilot, and related instruction sources with deterministic content rules. Ordinary policy language such as “never use production credentials” or “use X instead of Y” remains clean. Evidence composes only within a bounded directive and cannot cross headings or inert-region boundaries. Explicitly labeled examples and detector fixtures remain clean unless surrounding text tells the agent to execute them.

Base64 payloads are decoded only when structurally valid. Hex and percent-encoded payloads additionally require related decode-and-activate language before or after the payload. Decoding is strict, bounded to 2 KiB, one pass, and the decoded text must contain instruction semantics. Sensitive actions require a coherent directive, a concrete credential or instruction subject, appropriate material language, and—where applicable—an outbound destination; documentation schemas, hashes, placeholders, routine API authentication, and protective guidance remain clean.

The artifact stores the verdict, scope, file metadata, and bounded matched excerpts on each InstructionFile. It does not archive the complete file. For a large encoded token, the raw match is an exact bounded excerpt containing the encoded bytes that map to the decisive decoded semantics; the decoded preview supplies the readable context. A standalone override, identity rewrite, or bidirectional override becomes an instruction signal. Strong compound evidence—such as an override combined with identity rewriting, hidden control content, or a sensitive outbound action—becomes instruction poisoning.

Scope controls promotion:

Verdict and scope	Server finding
Signal in any collected scope	Medium INSTRUCTION_SIGNAL
Poisoning in recursive deep scope	Medium INSTRUCTION_SIGNAL
Poisoning in the exact project or user instruction scope	High POISONED_INSTRUCTIONS

The CLI prints the path, line, primary rule, and matched excerpt for each non-clean file. --quiet suppresses these lines. Agent exposure still requires a real LOADS_INSTRUCTIONS relationship; the detector does not invent one from file location.

Verification actions

The active planner performs four bounded actions when their prerequisites are present:

• MCP credential access first reads the exact resource anonymously. If that succeeds, AgentHound records public access and saves the content without presenting a credential. Otherwise, it follows with an authenticated read of the same resource.
• MCP Origin validation sends one anonymous ping with Origin: https://agenthound.invalid only after the same Streamable HTTP endpoint initialized anonymously. HTTP 403 records rejection; a response with the exact JSON-RPC request ID records acceptance; every other response is indeterminate. The probe does not initialize a session, follow redirects, or contact the .invalid origin.
• The ContextForge description round trip writes a scan-specific marker, observes it through MCP, restores the original immediately, and confirms restoration.
• Deep Ollama verification invokes a bounded embedding request to prove compute access.

The ContextForge action runs exclusively. Collection and other actions are drained before mutation, and nothing else runs until restoration is confirmed. Cleanup uses a separate 90-second context even when the main scan is interrupted.

Artifact and interruption behavior

AgentHound writes an ingest-valid artifact before collection and checkpoints after every meaningful result or action transition. Independent target and collector errors are recorded while unrelated work continues.

A checkpoint failure or unresolved cleanup stops forward planning. A deadline or signal finalizes the scan as interrupted. If recovery remains unresolved, retry it from the same artifact:

agenthound revert scan-<scan_id>.json

revert observes current state first, processes unresolved records newest-first, refuses to overwrite third-party changes, and checkpoints every attempt.

See the CLI reference for all flags and exit behavior.