Inventory And System Context

Inventory and system-context files

Evidentia projects are driven by three plain-text files that you author and keep in version control. evidentia init scaffolds all three (plus an empty .evidentia/ working directory) from a chosen preset; the day-to-day commands then read them:

File	Authored shape (Pydantic model)	Produced by	Consumed by
evidentia.yaml	evidentia_core.config.EvidentiaConfig	evidentia init	every evidentia command (project defaults)
system-context.yaml	evidentia_ai.risk_statements.templates.SystemContext	evidentia init	evidentia risk generate
my-controls.yaml	evidentia_core.models.control.ControlInventory	evidentia init	evidentia gap analyze --inventory

evidentia.yaml holds project-wide defaults (organization, framework scope, LLM settings). my-controls.yaml is your control inventory — the "what do we have today?" input to gap analysis. system-context.yaml describes the system the inventory applies to and is read only by the LLM-backed risk generate command. The example blocks below are the actual files produced by evidentia init --preset nist-moderate-starter with the default Acme Corporation organization; field tables are sourced field-by-field from the backing models.

The --preset flag (soc2-starter, nist-moderate-starter, hipaa-starter, cmmc-starter, empty) changes only the controls: block of my-controls.yaml. evidentia.yaml and system-context.yaml are preset-independent — they vary only with --organization and --frameworks. See the Quickstart and Configuration for the full flag list.

evidentia.yaml

An optional project config file discovered by walking the current directory up to the filesystem root for the first evidentia.yaml (evidentia_core.config.find_config_file). It supplies defaults for every command; precedence is CLI flag > EVIDENTIA_* env var > evidentia.yaml > built-in default. Any string value supports ${ENV_VAR} interpolation. Unknown keys are accepted but ignored (model_config = ConfigDict(extra="allow")), so legacy v0.2.0 keys do not break loading.

Generated by evidentia init --preset nist-moderate-starter:

# Evidentia project configuration.
#
# v0.2.1: this file is read by every `evidentia` command (was
# decorative in v0.1.x/v0.2.0). Precedence for every setting:
#   CLI flag > EVIDENTIA_* env var > this file > built-in default
#
# Supported keys as of v0.4.0 — everything else is accepted (for legacy
# compatibility) but ignored.

# Organization and system identity — overrides inventory-file values.
# Pairs with `gap analyze --organization` / `--system-name`.
organization: "Acme Corporation"
# system_name: "Your System Name"

# Default framework set for `gap analyze` when --frameworks is omitted.
# Populate with the canonical compliance scope for this project. CLI
# `--frameworks` replaces this list entirely (it does not union).
# Warning fires if this list has more than 5 frameworks.
frameworks:
  - nist-800-53-rev5-moderate
  - soc2-tsc

# LLM defaults for `risk generate`. Flag and
# EVIDENTIA_LLM_MODEL / EVIDENTIA_LLM_TEMPERATURE env vars win.
llm:
  model: "gpt-4o"
  temperature: 0.1

# ${ENV_VAR} interpolation is supported in any string value, e.g.:
#   organization: "${ORG_NAME}"
# so secrets and per-env settings can be hydrated from .env without
# committing them.

Honored keys (schema: evidentia_core.config.EvidentiaConfig, packages/evidentia-core/src/evidentia_core/config.py:68):

Key	Type	Required	Default	Description
organization	str | None	no	None	Organization name. Seeds the inventory's organization when the inventory file lacks one; overrides it when both are present. Pairs with gap analyze --organization.
system_name	str | None	no	None	System / product name surfaced in report headers alongside the organization. Pairs with gap analyze --system-name. (Commented out in the generated file.)
frameworks	list[str]	no	[]	Default framework IDs used by gap analyze when --frameworks is omitted. The CLI flag replaces this list — it does not union. A UserWarning fires if more than 5 frameworks are listed.
llm.model	str | None	no	None	Default LLM model name for risk generate (e.g. claude-sonnet-4-6). Overridden by --model or $EVIDENTIA_LLM_MODEL.
llm.temperature	float | None	no	None	Default LLM temperature for risk generate (0.0–2.0). Overridden by $EVIDENTIA_LLM_TEMPERATURE.

The llm block is the nested model LLMConfig (config.py:48). Both EvidentiaConfig and LLMConfig set extra="allow", so the field defaults above apply when a key is absent. Note the generated file writes llm.model: "gpt-4o" and llm.temperature: 0.1 — these come from the init starter template (generate_evidentia_yaml's llm_model / llm_temperature defaults), not from the model defaults, which are both None.

system-context.yaml

A description of the system your inventory applies to. It is read only by evidentia risk generate, which feeds it to the LLM so generated risk statements reference your real threat actors, data classifications, and components. It is not read by gap analyze. Loaded via SystemContext.from_yaml and validated against evidentia_ai.risk_statements.templates.SystemContext.

Generated by evidentia init --preset nist-moderate-starter:

# System context for AI risk statement generation.
# This file describes the system the inventory applies to; the LLM uses
# it to frame risk statements (threat sources, impact analysis).
organization: "Acme Corporation"
system_name: "Acme Corporation Platform"
system_description: |
  SaaS platform operated by Acme Corporation.
  Scope: authoritative business system.
data_classification:
  - PII
hosting: "(cloud provider + region)"
risk_tolerance: "low"
regulatory_requirements:
  - nist-800-53-rev5-moderate
  - soc2-tsc
employee_count: 100
customer_count: 10000
threat_actors:
  - "External threat actors (financial motivation)"
  - "Insider"
  - "Opportunistic ransomware groups"
existing_controls:
  # Reference control IDs the org already has in place.
components:
  # Describe the major components of the system.
  - name: "Web Application"
    type: web_app
    technology: "(stack)"
    data_handled: []
    location: "(region)"

In the generated file, system_name is derived as "{organization} Platform" and regulatory_requirements is seeded from the --frameworks list. existing_controls: is written as a comment-only key, so it parses to the empty-list default.

Fields (schema: evidentia_ai.risk_statements.templates.SystemContext, packages/evidentia-ai/src/evidentia_ai/risk_statements/templates.py:40):

Key	Type	Required	Default	Description
organization	str	yes	—	Organization name.
system_name	str	yes	—	Name of the system being assessed.
system_description	str	yes	—	Free-text description of the system's purpose, scope, and architecture.
data_classification	list[str]	no	[]	Types of data processed: PII, PHI, PCI-CDE, CUI, public.
hosting	str	yes	—	Hosting environment description, e.g. AWS (us-east-1, eu-west-1).
components	list[SystemComponent]	no	[]	System components with their technology stacks (see sub-table below).
threat_actors	list[str]	no	[]	Relevant threat-actor categories, e.g. External threat actors (financial), Nation-state, Insider.
existing_controls	list[str]	no	[]	Control IDs already implemented (context for risk generation).
frameworks	list[str]	no	[]	Target compliance frameworks. (Not written by init; the generated file uses regulatory_requirements instead.)
risk_tolerance	str	no	"medium"	Organization's risk tolerance: low, medium, high. (The generated file sets low.)
regulatory_requirements	list[str]	no	[]	Applicable regulations, e.g. HIPAA, PCI DSS, GDPR, CCPA, ITAR.
annual_revenue	str | None	no	None	Annual revenue range (used for impact assessment). Not written by init.
employee_count	int | None	no	None	Number of employees. (The generated file sets 100.)
customer_count	int | None	no	None	Number of customers / users. (The generated file sets 10000.)
notes	str | None	no	None	Free-text notes. Not written by init.

Each entry under components is a SystemComponent (templates.py:16):

Key	Type	Required	Default	Description
name	str	yes	—	Component name, e.g. Web Application.
type	str	yes	—	Component type: web_app, api, database, network, identity_provider, ci_cd.
technology	str	yes	—	Technology stack, e.g. React + Node.js, Amazon Redshift. (The generated placeholder is (stack).)
data_handled	list[str]	no	[]	Types of data this component processes, e.g. ['PII', 'PCI-CDE'].
location	str | None	no	None	Hosting location, e.g. AWS us-east-1, On-premises datacenter.
notes	str | None	no	None	Free-text notes.

my-controls.yaml

Your control inventory — the list of controls your organization actually implements, and the primary input to evidentia gap analyze. The analyzer compares these entries against the framework catalogs to find gaps. Validated against evidentia_core.models.control.ControlInventory.

Generated by evidentia init --preset nist-moderate-starter:

# Sample control inventory — replace with your organization's controls.
# Each entry's `id` should match a control ID in one of the frameworks
# you listed in evidentia.yaml (NIST 800-53, SOC 2, HIPAA, etc.).
#
# Status values: implemented | partially_implemented | planned | not_implemented | not_applicable
organization: "Acme Corporation"
controls:
  - id: AC-2
    title: "Account Management"
    status: implemented
    implementation_notes: "Managed via Okta with quarterly access reviews."
    owner: "IAM Team"

  - id: AC-3
    title: "Access Enforcement"
    status: partially_implemented
    implementation_notes: "RBAC for production; permission model migration in progress."

  - id: AU-2
    title: "Audit Events"
    status: planned
    implementation_notes: "Centralized logging deployment scheduled for Q3."

  - id: AU-6
    title: "Audit Review, Analysis, and Reporting"
    status: planned
    implementation_notes: "Awaiting SIEM deployment."

  - id: IA-2
    title: "Identification and Authentication"
    status: implemented
    implementation_notes: "MFA enforced on all employee accounts via Okta."

  - id: SC-8
    title: "Transmission Confidentiality and Integrity"
    status: implemented
    implementation_notes: "TLS 1.2+ enforced across all data flows."

  - id: SI-4
    title: "System Monitoring"
    status: partially_implemented
    implementation_notes: "CloudWatch alarms deployed; anomaly detection pending."

The soc2-starter, hipaa-starter, cmmc-starter, and empty presets emit the same top-level shape with a different controls: block (SOC 2 CC* criteria, HIPAA 164.* citations, CMMC 3.* practices, or a single placeholder comment).

Top-level fields (schema: evidentia_core.models.control.ControlInventory, packages/evidentia-core/src/evidentia_core/models/control.py:86):

Key	Type	Required	Default	Description
organization	str	yes	—	Organization name, used in report headers. Can be overridden by evidentia.yaml / --organization.
system_name	str | None	no	None	Optional system / product name the controls are scoped to (e.g. Prod SaaS Platform). Surfaces in report headers; pairs with --system-name.
controls	list[ControlImplementation]	yes	—	The control entries (see sub-table).
created_at	datetime	no	now (UTC)	When the inventory was created. Defaults to the load time if absent.
updated_at	datetime | None	no	None	When the inventory was last updated.
source_format	str	no	"evidentia"	Format of the source data: evidentia, oscal, csv, ciso-assistant. Set automatically by the loader.
source_file	str | None	no	None	Path the inventory was loaded from. Set automatically by the loader.
metadata	dict[str, Any]	no	{}	Additional metadata carried from the source format.

Each entry under controls is a ControlImplementation (control.py:28):

Key	Type	Required	Default	Description
id	str	yes	—	Organization-defined control ID, typically matching a framework ID (e.g. AC-2, CC6.1, A.9.2.1). Matched case-insensitively, whitespace-normalized.
title	str | None	no	None	Human-readable control title.
description	str | None	no	None	Description of how the organization implements this control.
status	ControlStatus	yes	—	Implementation status: implemented, partially_implemented, planned, not_implemented, not_applicable.
implementation_notes	str | None	no	None	Free-text notes on implementation details, compensating controls, or planned improvements.
responsible_roles	list[str]	no	[]	Roles or teams responsible for this control.
evidence_references	list[str]	no	[]	Paths, URIs, or IDs pointing to supporting evidence artifacts.
last_assessed	datetime | None	no	None	When this control was last assessed or validated.
owner	str | None	no	None	Email or name of the control owner.
frameworks	list[str]	no	[]	Frameworks this control is claimed to satisfy.
tags	list[str]	no	[]	Arbitrary tags for filtering and organization.

status is the ControlStatus enum (control.py:18); any value outside the five listed strings fails validation at load.

How gap analyze consumes these

evidentia gap analyze --inventory my-controls.yaml loads the inventory through evidentia_core.gap_analyzer.load_inventory (packages/evidentia-core/src/evidentia_core/gap_analyzer/inventory.py:89), which dispatches on the file extension:

Extension	Format	Notes
.yaml / .yml	Evidentia native	The shape documented above.
.json	OSCAL or CISO Assistant	Auto-detected: an OSCAL component-definition or a CISO Assistant export is parsed into the same ControlInventory.
.csv	CSV with header mapping	Columns mapped to ControlImplementation fields.

Resolution of the two project-wide inputs follows the documented precedence (gap.py, using get_default):

• Frameworks — --frameworks on the command line wins; otherwise the frameworks: list from evidentia.yaml is used; if neither is present the command errors. The CLI flag replaces the config list (it does not union).
• Organization / system name — --organization / --system-name win; otherwise evidentia.yaml's organization / system_name; otherwise the values inside the inventory file. Resolved overrides are applied with inv.model_copy(update=...) before the report header is rendered.

gap analyze does not read system-context.yaml — that file is consumed only by evidentia risk generate.

See also

• Configuration — the full evidentia.yaml key reference, all EVIDENTIA_* environment variables, and LLM provider keys.
• CLI reference — evidentia init, evidentia gap analyze, and evidentia risk generate flags.
• Bundled catalogs — the framework IDs you can list under frameworks: and match control ids against.
• Crosswalks — control-ID mappings across frameworks.