Reference

Configuration

The scanner and the service read three kinds of configuration. Each is a small JSON file. All of them live in your repository or next to it, so you can review them like code.

File	Purpose
`.vigil/agent.json`	Add a repository agent that scopes checks to paths.
`.vigil/policy.json`	Set the severity thresholds that `serve` uses.
`connectors/*.json`	Describe the HTTP sources `serve` polls.

#Repository agent

An agent is configuration, not code. .vigil/agent.json in the scanned folder defines one extra agent that runs in addition to the built-in codebase-guardian.

json

{
  "name": "payments-strict",
  "permissions": { "paths": ["services/payments/**"] },
  "checks": ["secrets", "deps", "iac", "zero_click"],
  "on_finding": "block"
}

Field	Required	Meaning
`name`	yes	A label for the agent.
`checks`	yes	A list drawn from `secrets`, `deps`, `iac` and `zero_click`. An unknown name is an error.
`permissions.paths`	no	Glob patterns relative to the scanned folder. Only findings in matching files count for this agent. Empty or missing means every file.
`on_finding`	no	`report` or `block`. Defaults to `report`. Any other value is an error.

on_finding set to block makes scan exit with status 1 when this agent finds a high or critical issue in its paths.

#Built-in agent

codebase-guardian ships with the scanner.

json

{
  "name": "codebase-guardian",
  "permissions": { "paths": ["**"] },
  "checks": ["secrets", "deps", "iac", "zero_click"],
  "on_finding": "block"
}

#Policy

.vigil/policy.json in the folder you pass to serve sets the thresholds.

json

{
  "block_at_severity": "high",
  "alert_at_severity": "medium"
}

Field	Default	Meaning
`block_at_severity`	`high`	Findings and connector items at or above this severity become a block.
`alert_at_severity`	`medium`	Connector items at or above this severity, and below the block level, become an alert.

Severities in order are info, low, medium, high and critical.

#Connectors

Each file in the connectors folder describes one HTTP source. ${NAME} is replaced with the environment variable NAME when the file loads, so secrets stay out of the file.

json

{
  "name": "siem-alerts",
  "type": "http",
  "url": "https://siem.example.com/api/alerts",
  "method": "GET",
  "headers": { "Authorization": "Bearer ${SIEM_TOKEN}" },
  "response_path": "results",
  "id_key": "id",
  "title_key": "title",
  "severity_key": "severity"
}

Field	Default	Meaning
`name`	required	A label for the source.
`url`	required	The endpoint to fetch. A connector without a `name` and a `url` is ignored.
`method`	`GET`	The HTTP method.
`headers`	none	Request headers.
`body`	none	A request body, sent as given.
`response_path`	whole response	A dotted path into the JSON response that holds the list of items.
`id_key`	`id`	The key in each item used as its identifier.
`title_key`	`title`	The key used as the summary.
`severity_key`	`severity`	The key used for severity. A missing value means `info`.

If a source cannot be reached or does not return JSON, Kelvar records an error insight and keeps going.

#Home and environment

The Kelvar system keeps its state in the Home directory, which is ~/.vigil unless VIGIL_HOME says otherwise. The registry of agents, interfaces and rooms lives in the Home. You normally change it through the app, or by asking Home to author a change. See Security agents and Permissions and sandboxing.