Cynative Agents: Named Prompts for Security Research

Agents are Markdown files that supply the prompt for a Cynative run. Use built-in agents, shadow them, or write your own for repeatable security research.

An agent is a Markdown file that supplies the prompt for a Cynative run. Where a free-form question is useful for exploratory or one-off research, an agent turns a recurring task — privilege escalation paths, public data store exposure, supply chain risk — into a versioned, reviewable artifact you can run consistently across environments. Because the prompt lives in a file, it can be code-reviewed, committed to a repository, and shared with the rest of your team, while the run itself stays read-only and tied to your own credentials.

Two sources of agents

Agents come from exactly two places, resolved in order — first match wins:

Precedence	Source	Location
1	user	~/.cynative/agents/
2	built-in	embedded in the binary

The binary ships 45 built-in agents covering AWS, Azure, GCP, GitHub, and Kubernetes. To add your own, create the directory and write Markdown files into it. Cynative does not create the directory for you:

mkdir -p ~/.cynative/agents

Any file you place there is immediately available as --agent <filename-without-extension>. A user agent with the same name as a built-in takes precedence — see Shadowing below.

Running agents

Pass --agent <name> with -p for a single non-interactive run, with an optional task to scope it further, or without -p to seed an interactive session:

cynative -p --agent aws-public-datastores
cynative -p --agent aws-public-datastores "AWS account 128149835728 only"
cynative --agent aws-public-datastores   # seeds interactive session

The optional positional argument after the agent name is your task — a scoping instruction passed alongside the agent’s own prompt. When you provide one, it appears in the prompt as a user instruction: section between the agent’s description and its body. When you omit it, that section is left out entirely.

Listing and inspecting agents

cynative agents list           # every agent, source, status
cynative agents show <name>    # print the exact file

agents list shows every agent from both sources, with its source and status. agents show writes the file bytes to stdout and the source path to stderr — useful for review, and for copying a built-in as the basis for a custom agent. Neither command reads your configuration or touches credentials, so both work on a fresh install before Cynative is configured.

When a user agent shadows a built-in of the same name, agents list marks the loser:

NAME    DESCRIPTION                 SOURCE   STATUS
alpha   Your copy of alpha.         user     active
alpha   The built-in alpha.         builtin  shadowed by user
beta    A built-in agent.           builtin  active
broken                              user     invalid (blocking)

A file that is found but unusable — malformed, unreadable, oversized, a symlink, or not a regular file — appears as invalid (blocking). It still claims the name, so the run fails with an error naming the file. Resolution never falls through to the built-in.

Composing with other flags

--agent composes with the rest of Cynative’s flags:

Combination	Effect
--agent + -p	Single non-interactive run; exits with a verdict code.
--agent + -p + --auto-approve	Fully unattended; skips the per-call keystroke. Suitable for CI.
--agent + --verbose	Streams each inner tool call as it runs.
--agent + --config	Uses an alternate config file for LLM and connector settings.
--agent + piped stdin	Piped bytes are fenced in <piped_input> tags and treated as untrusted data to analyse — the agent file is already supplying the instruction.

For example, to triage a findings file with an agent in a CI pipeline:

cat findings.json | cynative -p --auto-approve --agent triage-findings

Trust

Agents come only from ~/.cynative/agents/ and the binary. Selection is always explicit by name: the model cannot introduce an agent or choose one on its own. An agent only supplies text — approvals, connector authorization, and the read-only ceilings are all enforced by Cynative when each tool call runs, regardless of what the agent’s prompt says. An agent cannot reach anything your credentials do not already allow.

Every run prints which agent file was used and its source path — for example:

Agent: my-aws-public-datastores  [user: /home/you/.cynative/agents/my-aws-public-datastores.md]

cynative agents list shows the same information ahead of time, and every audited tool call records the agent’s name, source, and file digest so a finding can be traced back to the exact prompt that produced it.