Configuration

Every command-line flag and environment variable AgentShield reads. Flags use pflag; discovery options are registered by their owning plugin and always carry that plugin’s name as a prefix.

Flags accept -flag or --flag. When a flag’s default comes from an environment variable, an explicit flag wins.

Every binary prints its version and commit and exits with --version (for agentshield-detector-rules, as the only argument). Release builds carry the tag and commit; a go build from a checkout reports the module version or dev and the VCS revision when Go recorded one.

agentshield

The main service: discovery, telemetry, API, UI, and (optionally) detection with agentic investigation and Deployment rule authoring.

Server and storage

Telemetry sink

Discovery

Discovery needs at least one source: startup fails if --kubernetes-disable is set without --aws-region (unless --disable-discovery is set).

Detection and model-calling features

Nothing calls a model unless one of the two feature flags below is set. Detection runs when either is enabled and makes no model calls itself; there is no detection-only mode. See Detection and investigation.

Detection

Agentic investigation

Deployment rule authoring

API key lookup order: --model-api-key, then AGENTSHIELD_MODEL_API_KEY, then the conventional key for the selected provider (OPENAI_API_KEY or ANTHROPIC_API_KEY).

Renamed in this release: --reasoning-effort is --model-reasoning-effort, --reasoning-retrieval is --agentic-investigation-retrieval, --reasoning-consumer is --detection-consumer, --reasoning-interval is --detection-interval, and --deployment-author-poll-interval and --deployment-author-timeout are --deployment-rule-authoring-poll-interval and --deployment-rule-authoring-timeout. Setting --model-endpoint no longer enables any feature by itself.

agentshield rules

Manages CEL rulesets, reviews Deployment rules, and inspects detection signals and queues through agentshield rules <validate|save|activate|show|jobs|job|review|workload-rules|signals|investigations> [flags]. The agentshield-detector-rules executable remains as a compatibility entry point using the same implementation. See Detection rules.

The command has a 30-second overall timeout. validate does not open a database; other actions require AGENTSHIELD_DATABASE_URL.

agentshield-deployment-author

Runs the Deployment rule author once against a local JSON context. No database. See Detection rules.

agentshield-reasoning-mcp

Serves MCP tools over streamable HTTP at /mcp. The default listener is 127.0.0.1:8090; use --listen to change it only behind authenticated infrastructure. The server reads the packet and optional pinned telemetry context files and does not contact a database or model.

Environment variables

Makefile and Docker Compose

The eval scripts in evals/scripts/ read more variables (cluster name, tool versions, output directory); see evals/scripts/lib.sh.

Status logs

Each long-running loop in agentshield logs what it is doing at Info level, without a line per iteration. Rare events get their own line: a plugin starting, a Deployment rule job being claimed and drafted, an investigation job starting and finishing, detection rules matching, and the detector loading a changed ruleset or workload rule set. Each loop also logs one status line with its counters since the previous line: at most every 15 seconds while it does work, and at most once a minute while it is idle.

A Deployment rule draft that stays queued is usually inside its baseline window; waiting_for_baseline and next_baseline_ends_in show it. Author now in the UI, or POST /api/v1/workloads/{id}/rule-drafts, skips the wait.