Manifest Format¶
Complete reference for the .clad.toml manifest format. Every section is annotated with field types, defaults, and examples.
[tool] -- Tool Metadata¶
[tool]
name = "nmap_scan" # Required. Unique tool identifier.
version = "1.0.0" # Required. Semver, tracks CLI tool version.
binary = "nmap" # Binary name or path. Required for oneshot shell.
description = "Network port scanning and service detection" # Required.
mode = "oneshot" # "oneshot" | "session" | "browser". Advisory; derived when absent.
timeout_seconds = 600 # Execution timeout. Default: 60. Must be > 0.
risk_tier = "low" # "low" | "medium" | "high" | "critical". high/critical are gated.
human_approval = false # Gated by the default policy gate when true. Default: false.
network_egress = true # Tool reaches the network: network-target args must set block_internal.
allow_interpreter = false # Permit sh/bash/python3/node/... as argv[0]. Default: false.
dispatch = "exec" # "exec" (default) | "callback" (validator-only embedding)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | yes | -- | Unique tool identifier, used for MCP registration |
version |
string | yes | -- | Semver version of the underlying CLI tool |
binary |
string | yes (oneshot shell) | -- | Binary name or path. When set with an exec/template command, its basename must equal the basename of argv[0] or the manifest is refused |
description |
string | yes | -- | Human-readable description (included in MCP schema) |
mode |
string | no | derived | "oneshot", "session", or "browser". Advisory only; derived from which backend section is present when absent |
timeout_seconds |
integer | no | 60 |
Maximum execution time before the SIGTERM/SIGKILL process-group kill. 0 is refused at load (timeout_seconds must be greater than zero) |
risk_tier |
string | no | "low" |
"low", "medium", "high", or "critical". high and critical are denied by the default policy gate (risk_tier '<t>' requires explicit approval) unless --approve or an approving gate is supplied |
human_approval |
boolean | no | false |
When true, the default policy gate denies execution (manifest requires human approval (human_approval = true)); --approve or an approving gate is required |
network_egress |
boolean | no | false |
Declares that the tool reaches the network. When true, every argument of type scope_target, url, ip_address, cidr, or a custom type based on one of those must set block_internal = true, or the manifest is refused at load. The same lint applies automatically when tool.binary, exec[0], or the template's first token is a known egress binary (curl, wget, nmap, nc, ncat, netcat, masscan, telnet, ssh, ping, fping, httpie, http, wfuzz, ffuf, hydra, nikto) and to every [http] and [browser] manifest |
allow_interpreter |
boolean | no | false |
Permits argv[0]'s basename to be sh, bash, zsh, dash, ksh, csh, tcsh, fish, ash, busybox, env, eval, xargs, python, python2, python3, perl, ruby, node, deno, bun, lua, php, or awk. Refused at load otherwise |
dispatch |
string | no | "exec" |
"exec" runs a backend; "callback" is a validator-only embedding with no backend or [output] required |
[tool.cedar] -- Cedar Policy Metadata¶
[tool.cedar]
resource = "PenTest::ScanTarget" # Cedar resource type for authorization
action = "execute_tool" # Cedar action
The ORGA Gate builds the Cedar authorization request from these fields plus runtime context (agent identity, phase, environment). Cedar policies in policies/ reference resource.tool_name to match against specific tools.
[tool.evidence] -- Evidence Capture¶
[tool.evidence]
output_dir = "{evidence_dir}/{scan_id}-nmap" # Evidence output path template
capture = true # Capture raw output to file. Default: true.
hash = "sha256" # Hash algorithm for output_hash. Default: "sha256".
When capture = true, the executor writes the raw tool output to output_dir and includes the SHA-256 hash in the evidence envelope for tamper detection. screenshots is accepted for browser manifests.
[tool.limits] -- Child Resource Limits¶
[tool.limits]
nproc = 4096 # RLIMIT_NPROC. Default: unset (not applied).
nofile = 1024 # RLIMIT_NOFILE. Default: 1024.
fsize_bytes = 1073741824 # RLIMIT_FSIZE. Default: 1 GiB.
address_space_bytes = 2147483648 # RLIMIT_AS. Only applied when declared.
cpu_seconds = 600 # RLIMIT_CPU. Only applied when declared.
The Rust and Python runtimes apply these as rlimits on the child via a pre-exec hook (together with RLIMIT_CORE = 0 and a 0077 umask). Go and JavaScript cannot set child rlimits portably and skip this section; the keys are still parsed and validated there, but deployments on those runtimes must enforce limits externally (cgroups, container limits, or ulimit in the hosting process).
[tool.schemapin] -- SchemaPin Verification¶
SchemaPin signs .clad.toml files directly as first-class artifacts. No [tool.schemapin] section is needed in the manifest. The manifest stays clean.
Signing (tool vendor):
The signature and hash are published in the vendor's .well-known/schemapin.json discovery document. Verification happens at the runtime level, not the manifest level. See the Design Specification for the full verification flow.
SchemaPin v1.4 (alpha) — Lifecycle, Lineage, DNS¶
The signing command supports three additive optional features from SchemaPin v1.4-alpha. None of them require manifest changes — they are options on schemapin-sign. Recommended for any production manifest:
# Versioned release with TTL + lineage
schemapin-sign tools/nmap_scan.clad.toml \
--expires-in 6mo \
--schema-version "$(awk -F\" '/^version[[:space:]]*=/ {print $2; exit}' tools/nmap_scan.clad.toml)" \
--previous-hash "$(jq -r '.skill_hash' tools/nmap_scan.clad.toml.sig.prior 2>/dev/null || true)"
What each flag does:
--expires-in 6mo— adds anexpires_atfield. Verifiers past the expiry emit asignature_expiredwarning rather than failing. Forces re-signing on a cadence; surfaces stale tooling for policy gating.--schema-version "$TOOL_VERSION"— embeds the manifest's[tool] versionsemver into the signature. Surfaced onVerificationResult.schema_versionfor runtime version policy.--previous-hash "$PREV_HASH"— claims this signature is the legitimate successor of the prior one. Pair withverify_chainat the runtime layer to fail closed on rug-pull substitutions.
Vendors SHOULD also publish a _schemapin.{vendor-domain} TXT record pointing at the same key fingerprint as .well-known/schemapin.json — runtimes that adopt DNS TXT cross-verification then fail closed on mismatches between the HTTPS hosting channel and the DNS channel.
See SchemaPin v1.4 features in ToolClad for the full operational guide and per-language verifier examples.
[args.*] -- Parameter Definitions¶
Each parameter is a TOML table under [args]:
[args.target]
position = 1 # Positional index in the command template
required = true # Is this parameter mandatory?
type = "scope_target" # One of 15 built-in types or a custom type
block_internal = true # Refuse loopback/private/metadata targets; resolve hostnames fail-closed
scope_check = true # Allowlist against scope/scope.toml (fail-closed when no file is found)
description = "Target CIDR, IP, or hostname"
[args.scan_type]
position = 2
required = true
type = "enum"
allowed = ["ping", "service", "version", "syn", "os_detect"]
description = "Type of scan to perform"
[args.threads]
position = 3
required = false
type = "integer"
min = 1 # Minimum value (integer type)
max = 64 # Maximum value (integer type)
clamp = true # Clamp to range instead of rejecting. Default: false.
default = 4 # Default value when not provided
[args.module_path]
type = "string"
pattern = "^(exploit|auxiliary|post)/[a-zA-Z0-9_/]+$" # Regex validation
sanitize = ["injection"] # Explicit injection sanitization
[args.target_url]
type = "url"
schemes = ["http", "https"] # Allowed URL schemes (default); dangerous schemes are always refused
block_internal = true # Required when the tool fetches the URL
scope_check = true # Extract host for scope validation
[args.headers]
type = "string"
allow_whitespace = true # Permit spaces; honored only when [command] declares exec = [...]
default = ""
[args.offset]
type = "integer"
allow_leading_dash = true # Permit a negative value (otherwise a leading - or + is refused)
[args.wordlist]
type = "path" # No `..` component, no absolute paths
required = false
Arg Field Reference¶
| Field | Type | Description |
|---|---|---|
position |
integer | Positional index for template ordering |
required |
boolean | Mandatory parameter. Default: false |
type |
string | Built-in type name or custom type. See Type System |
description |
string | Human-readable description (included in MCP schema) |
default |
any scalar | Default value when parameter is not provided |
allowed |
array | Valid values for enum type |
pattern |
string | Regex constraint for string and regex_match types. Anchored: compiled as ^(?:pattern)$ |
sanitize |
array | Sanitization rules: ["injection"] |
min |
integer | Minimum for integer type |
max |
integer | Maximum for integer type |
min_float |
number | Minimum for number type |
max_float |
number | Maximum for number type |
clamp |
boolean | Clamp to range instead of rejecting (integer, number). Default: false |
schemes |
array | Allowed URL schemes for url type. Default: ["http", "https"]. javascript, data, file, blob, about, gopher, dict, ftp, ldap, jar, netdoc, mailto, ws, wss are refused even if listed |
scope_check |
boolean | Check the value (host for url) against scope/scope.toml; applies to scope_target, url, ip_address, cidr. Fail-closed. Default: false |
block_internal |
boolean | Block loopback, private, CGNAT, documentation, and reserved ranges and resolve hostnames fail-closed; applies to scope_target, url, ip_address, cidr. Link-local and internal names are blocked regardless. Mandatory on egress tools. Default: false |
allow_whitespace |
boolean | Permit whitespace in a string-derived value. Honored only when [command] declares exec directly; never for url. Default: false |
allow_leading_dash |
boolean | Permit a value (or numeric result) that starts with - or +. Default: false |
Any other key under [args.<name>] is refused at load.
Mappings in Args¶
When an enum arg has a corresponding entry in [command.mappings], the enum value is translated to CLI flags at command construction time. See Command Construction for details.
[command] -- Shell Command Construction¶
[command]
exec = ["nmap", "{_scan_type_flags}", "--max-rate", "{max_rate}", "-oX", "{_output_file}", "{target}"]
end_of_options = "--" # Optional. Only "--" is accepted.
exec is the canonical form: one argv element per entry, placeholders as whole unquoted tokens, {{/}} for literal braces, values never re-split. Use executor when invocation logic exceeds what exec can express.
| Field | Type | Description |
|---|---|---|
exec |
array | Canonical argv array |
template |
string | Deprecated. Tokenized into exec at load with a warning; a placeholder inside quotes or unbalanced quotes rejects the manifest. Will be removed in the next minor release |
executor |
string | Escape-hatch script; receives TOOLCLAD_ARG_* and friends in an otherwise cleared environment |
end_of_options |
string | Only "--". Inserts a literal -- before the first user-argument token |
defaults |
table | Open map of default values for placeholders |
mappings |
table | Open map of [command.mappings.<arg>] tables |
conditionals |
table | [command.conditionals.<name>] entries with when and template |
See Command Construction for details on mappings, conditionals, defaults, and the escape hatch.
[command.defaults]¶
[command.mappings.*]¶
[command.mappings.scan_type]
ping = "-sn -PE"
service = "-sT -sV --version-intensity 5"
syn = "-sS --top-ports 1000"
Maps enum values to CLI flag strings. The mapped result is available as {_scan_type_flags} -- the variable is always _<arg_name>_flags; no other alias is recognized. The mapped string is tokenized (it is manifest-controlled) and spliced into the argv where the placeholder appears.
[command.conditionals]¶
[command.conditionals]
service_port = { when = "port != 0", template = "-s {port}" }
username_file = { when = "username_file != ''", template = "-L {username_file}" }
single_user = { when = "username != '' and username_file == ''", template = "-l {username}" }
Include template fragments only when conditions are met. Each conditional is exposed as {_<name>} ({_service_port} above) and its template is tokenized at load with the same rules as [command].template. See Command Construction for the full when expression syntax.
[http] -- HTTP Request Backend¶
[http]
method = "POST"
url = "https://slack.com/api/chat.postMessage"
headers = { "Authorization" = "Bearer {_secret:slack_token}", "Content-Type" = "application/json" }
body_template = '{"channel": "{channel}", "text": "{message}"}'
success_status = [200]
error_status = [400, 401, 403, 404, 429]
| Field | Type | Description |
|---|---|---|
method |
string | HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD |
url |
string | URL template with {arg_name} and {_secret:name} placeholders |
headers |
table | Header key-value pairs with template variable support |
body_template |
string | Request body template with {arg_name} interpolation |
success_status |
array | HTTP status codes that indicate success |
error_status |
array | HTTP status codes that indicate error |
{_secret:name} references are expanded on these templates before any argument is interpolated; URL values are percent-encoded, body values are JSON-escaped, redirects are not followed, and the envelope's command holds the unexpanded url. [http] manifests are treated as network_egress = true, so every network-target argument must set block_internal = true. See HTTP and MCP Backends for details.
[mcp] -- MCP Proxy Backend¶
[mcp]
server = "github-mcp" # Named MCP server from symbiont.toml
tool = "create_issue" # Upstream tool name
[mcp.field_map]
repo = "repository" # ToolClad arg name -> upstream param name
labels = "label_names"
| Field | Type | Description |
|---|---|---|
server |
string | Named MCP server connection from symbiont.toml |
tool |
string | Upstream MCP tool name to invoke |
field_map |
table | Argument name mapping: ToolClad name to upstream name |
Unmapped fields pass through with the same name. See HTTP and MCP Backends for details.
Parsed, not executed. The reference runtimes validate
[mcp]manifests and return adelegation_previewenvelope (field-mapped arguments, no upstream call). Forwarding to the MCP server is the job of a hosting runtime.
[output] -- Output Handling¶
[output]
format = "xml" # "text" | "json" | "xml" | "csv" | "jsonl"
parser = "builtin:xml" # builtin:* only; anything else is refused at load
envelope = true # Wrap in evidence envelope. Default: true.
max_bytes = 8388608 # Cap on stdout and stderr (each). Default: 8 MiB.
| Field | Type | Description |
|---|---|---|
format |
string | Output format hint |
parser |
string | One of the builtin:* names below. A script path is refused at load (custom output parsers are not supported by the reference runtimes) |
envelope |
boolean | Wrap results in an evidence envelope. Default: true |
schema |
table | Mandatory output schema (see below) |
max_bytes |
integer | Cap on captured stdout and stderr, each. Overflow stops capture and sets output_truncated: true. Default: 8388608 |
Built-in Parsers¶
| Parser | Produces | Use Case |
|---|---|---|
builtin:json |
Pass-through | Tools with native JSON output |
builtin:xml |
JSON conversion | nmap, Nessus, OWASP ZAP |
builtin:csv |
Array of objects | Spreadsheets, log files |
builtin:jsonl |
Array of objects | Nuclei, streaming tools |
builtin:text |
{ "raw_output": "..." } |
Unstructured text (default) |
Custom Parsers (Not Supported)¶
A parser value that is not one of the builtin:* names above -- for example parser = "scripts/parse-outputs/parse-nmap-xml.py" -- is refused at load by the reference runtimes. There is no mechanism for an external script to run in the output pipeline. builtin:xml additionally refuses input containing <!DOCTYPE or <!ENTITY.
[output.schema] -- Output Schema (Mandatory)¶
Every manifest must declare the expected shape of parsed results. The schema is JSON Schema-compatible and maps directly to MCP outputSchema.
[output.schema]
type = "object"
[output.schema.properties.hosts]
type = "array"
description = "Discovered hosts with open ports and services"
[output.schema.properties.hosts.items.properties.ip]
type = "string"
[output.schema.properties.hosts.items.properties.ports]
type = "array"
[output.schema.properties.hosts.items.properties.ports.items.properties.port]
type = "integer"
[output.schema.properties.hosts.items.properties.ports.items.properties.service]
type = "string"
For simple tools:
[output.schema]
type = "object"
[output.schema.properties.raw_output]
type = "string"
description = "Raw command output text"
The schema serves two purposes:
- MCP
outputSchemageneration -- the LLM sees what data shape it will receive before proposing a tool call - Parser output validation -- the executor validates parsed results against the schema with a bundled JSON-Schema subset validator (
type,properties,required,items,additionalPropertiesas a boolean,enum,minimum,maximum,minLength,maxLength,pattern; unknown keywords are ignored). Validation is fail-closed: a violation sets the envelope status toschema_error, replacesresultswith{"schema_error": "<path>: <message>"}, and preserves the raw output underresults.raw_output
[session] -- CLI Session Mode¶
Parsed, not executed. The reference runtimes load and validate
[session]manifests (and servevalidate/schemafor them) but refuseexecutewithsession mode is parsed but not yet executable in the reference implementation. Execution is provided by a hosting runtime.
[session]
startup_command = "msfconsole -q -x 'color false'"
ready_pattern = "^msf[0-9].*> $"
startup_timeout_seconds = 30
idle_timeout_seconds = 300
session_timeout_seconds = 1800
max_interactions = 100
[session.interaction]
input_sanitize = ["injection"]
output_max_bytes = 1048576
output_wait_ms = 2000
[session.commands.use_module]
pattern = "^use (exploit|auxiliary|post)/[a-zA-Z0-9_/]+$"
description = "Load a Metasploit module"
risk_tier = "medium"
[session.commands.run]
pattern = "^(run|exploit)$"
description = "Execute the loaded module"
risk_tier = "high"
human_approval = true
See Session Mode for the full reference.
[browser] -- Browser Mode¶
Parsed, not executed. The reference runtimes load and validate
[browser]manifests but refuseexecutewithbrowser mode is parsed but not yet executable in the reference implementation. They do enforce the egress lint at load:[browser]manifests count asnetwork_egress = true, so every network-target command argument must setblock_internal = true.
[browser]
engine = "cdp-direct"
connect = "launch" # "launch" = spawn headless | "live" = attach to Chrome
headless = true
startup_timeout_seconds = 10
session_timeout_seconds = 600
idle_timeout_seconds = 120
max_interactions = 200
[browser.defaults]
extract_mode = "accessibility_tree" # "accessibility_tree" | "html" | "text"
[browser.scope]
allowed_domains = ["*.example.com", "docs.example.com"]
blocked_domains = ["*.evil.com"]
allow_external = false
[browser.commands.navigate]
description = "Navigate a tab to a URL"
risk_tier = "medium"
args.url = { type = "url", schemes = ["https"], block_internal = true, scope_check = true }
[browser.commands.click]
description = "Click an element by CSS selector"
risk_tier = "low"
args.selector = { type = "string", pattern = "^[a-zA-Z0-9_.#\\[\\]=\"' >:()-]+$" }
[browser.commands.submit_form]
description = "Submit a form"
risk_tier = "high"
human_approval = true
args.selector = { type = "string" }
Scope Enforcement¶
There is no [tool.scope] section; a manifest containing one is refused as an unknown key. Scope enforcement is declared per argument: any parameter of type scope_target, url, ip_address, or cidr that sets scope_check = true is validated against the project scope file during argument validation, before the command is built. Without scope_check = true no allowlisting happens -- scope_target by itself is only a shape check.
# scope/scope.toml
[scope]
allowed_cidrs = ["10.0.1.0/24"]
allowed_domains = ["example.com", "*.example.com"]
blocked_cidrs = []
blocked_domains = []
The file is found via TOOLCLAD_SCOPE_FILE, or by searching for scope/scope.toml upward from the manifest's directory. Unknown keys in the scope file are refused. If scope_check = true and no file is reachable, the value is rejected (fail-closed). Blocked rules win over allowed rules; *.example.com matches strict subdomains at any depth but not the apex or evil-example.com; an IP must be contained in an allowed CIDR and a CIDR value must be fully contained. See Security Model: Scope Enforcement.
Unknown Keys¶
Every parser refuses keys it does not know, at load, with unknown key '<section>.<key>' in manifest. toolclad validate --allow-unknown-keys downgrades this to a printed warning; library loading is always strict. The complete allowlist:
[tool] name version binary description timeout_seconds risk_tier
human_approval dispatch mode network_egress allow_interpreter
cedar evidence limits
[tool.cedar] resource action
[tool.evidence] output_dir capture hash screenshots
[tool.limits] nproc nofile fsize_bytes address_space_bytes cpu_seconds
[args.<n>] position required type description default allowed pattern
sanitize min max min_float max_float clamp schemes
scope_check block_internal allow_leading_dash allow_whitespace
[command] template exec executor defaults mappings conditionals
end_of_options
[command.conditionals.<n>] when template
[output] format parser envelope schema max_bytes
[http] method url headers body_template success_status error_status
[mcp] server tool field_map
[session] startup_command ready_pattern startup_timeout_seconds
idle_timeout_seconds session_timeout_seconds max_interactions
interaction commands child_detection
[session.interaction] input_sanitize output_max_bytes output_wait_ms
[session.commands.<n>] pattern description risk_tier human_approval
extract_target args
[session.child_detection] pattern type manifest
[browser] engine headless connect extract_mode startup_timeout_seconds
session_timeout_seconds idle_timeout_seconds max_interactions
scope commands state defaults
[browser.defaults] extract_mode
[browser.scope] allowed_domains blocked_domains allow_external
[browser.commands.<n>] description risk_tier human_approval args
[browser.state] fields
[args.*].default accepts any scalar. [command.defaults] and [command.mappings] are open maps whose keys are user-chosen names. [output.schema] is JSON Schema and is not key-checked.
Complete Annotated Example¶
# tools/nmap_scan.clad.toml -- Full manifest with all sections
#
# There is deliberately no free-form flag parameter. An argument whose value is
# interpolated as nmap options is an option-injection channel; every supported
# invocation is an entry in [command.mappings.scan_type] instead.
[tool]
name = "nmap_scan"
version = "1.0.0"
binary = "nmap"
description = "Network port scanning and service detection"
timeout_seconds = 600
risk_tier = "low"
network_egress = true
[tool.cedar]
resource = "PenTest::ScanTarget"
action = "execute_tool"
[tool.evidence]
output_dir = "{evidence_dir}/{scan_id}-nmap"
capture = true
hash = "sha256"
# --- Parameters ---
[args.target]
position = 1
required = true
type = "scope_target"
# nmap connects to this target: default-deny internal/SSRF ranges. Under
# block_internal a hostname must resolve to a public address, and a CIDR must
# not overlap a blocked range.
block_internal = true
description = "Target CIDR, IP, or hostname"
[args.scan_type]
position = 2
required = true
type = "enum"
allowed = ["ping", "service", "version", "syn", "os_detect", "aggressive", "vuln_script"]
description = "Type of scan to perform"
# --- Command Construction ---
#
# Array form: every element is one argv entry, dispatched straight to execve.
# {_scan_type_flags} is the only multi-token placeholder; its value comes from
# the mapping table below, which is manifest-controlled, not agent-supplied.
[command]
exec = [
"nmap",
"{_scan_type_flags}",
"--max-rate", "{max_rate}",
"-oX", "{_output_file}",
"--no-stylesheet",
"-v",
"{target}",
]
[command.defaults]
max_rate = 1000
[command.mappings.scan_type]
ping = "-sn -PE"
service = "-sT -sV --version-intensity 5"
version = "-sV --version-all --top-ports 1000"
syn = "-sS --top-ports 1000"
os_detect = "-sS -O --osscan-guess"
aggressive = "-A -T4 --top-ports 10000"
vuln_script = "-sV --script=vuln --script-timeout 60s"
# --- Output ---
[output]
format = "xml"
parser = "builtin:xml"
envelope = true
max_bytes = 8388608
[output.schema]
type = "object"
[output.schema.properties.hosts]
type = "array"
description = "Discovered hosts with open ports and services"
[output.schema.properties.hosts.items.properties.ip]
type = "string"
[output.schema.properties.hosts.items.properties.ports]
type = "array"
[output.schema.properties.hosts.items.properties.ports.items.properties.port]
type = "integer"
[output.schema.properties.hosts.items.properties.ports.items.properties.protocol]
type = "string"
[output.schema.properties.hosts.items.properties.ports.items.properties.service]
type = "string"
[output.schema.properties.hosts.items.properties.ports.items.properties.version]
type = "string"