Skip to content

API Stability

Jump to bottom
evidentia-wiki-sync[bot] edited this page May 31, 2026 · 2 revisions

Auto-generated mirror. This page mirrors docs/api-stability.md, the canonical source of truth. Do not edit this file directly; edit docs/api-stability.md and re-run scripts/wiki/sync_mirrors.py.

API stability commitments — NORMATIVE

Status: NORMATIVE as of v0.9.7 (2026-05-19). Promoted from DRAFT during the v0.9.7 P2.1 v1.0-prep cycle per the docs/v1.0-transition.md Candidate B framing. Promoted ahead of v1.0 so the v0.9.x → v1.0.0 transition does not require any additional API-contract changes — the contract is set and tested over the remaining v0.9.x line.

Scope: defines which surfaces carry semantic-versioning guarantees, and which surfaces remain free to change without a major-version bump. Operators MAY rely on the frozen surfaces; integrators MAY build against them with confidence that Evidentia will not break them without a deprecation cycle.

Pre-v1.0 vs post-v1.0 semantics: this NORMATIVE document is already binding — Evidentia will not knowingly break a frozen surface listed below in any v0.9.x release. The v1.0.0 release itself does not add new constraints; it ratifies the contract already in force.

Canonical location: docs/api-stability.md Cross-references: v1.0-transition.md, enterprise-grade.md, release-checklist.md, deprecation-calendar.md

Versioning semantics (post-v1.0)

Evidentia follows Semantic Versioning 2.0.0 with the following interpretation:

Bump Meaning Example
Major (X.0.0) Breaking change to a frozen surface Remove a Pydantic field, rename a CLI flag
Minor (1.X.0) New functionality, additive-only changes to frozen surfaces New EventAction, new CLI command, new optional model field
Patch (1.0.X) Bug fixes, security patches, doc updates, catalog content refreshes CVE fix, threshold default adjustment, typo

Pre-v1.0 (v0.9.7 onward — this document NORMATIVE): the contract listed in this document is binding. Breaking changes to frozen surfaces require a deprecation cycle per the policy in § "Deprecation policy" below. The v1.0.0 release ratifies (does not expand) the contract already in force.

Earlier pre-v1.0 (v0.9.0 – v0.9.6): minor bumps may have contained breaking changes to any surface. The v0.9.x line was the "stabilization window" where the public contract was identified and documented in DRAFT form.

Frozen surfaces

These surfaces carry full semver guarantees at v1.0+. Breaking changes require a major-version bump with a deprecation cycle.

1. Pydantic model fields

Package: evidentia_core.models.*

All exported model classes have stable field names and types. Adding optional fields (with defaults) is a minor-bump change. Renaming, removing, or changing the type of an existing field is a major-bump trigger.

Frozen models (48+ classes across 18 modules; v0.10.0-confirmed):

Module Key models
common.py FrameworkMetadata, ControlMapping, EvidentiaModel
control.py Control, ControlFamily, ControlImplementation, ControlInventory, ControlStatus
evidence.py EvidenceArtifact, EvidenceBundle, EvidenceType, EvidenceSufficiency. v0.9.5+ adds EvidenceArtifact.version / lineage_id / predecessor_id Optional fields + new_version() factory helper; these are now frozen.
finding.py (v0.10.0+) SecurityFinding, Finding (v0.10.1 alias — both names refer to the same class), FindingStatus, ComplianceStatus. Frozen following the v0.10.0 OCSF-alignment evolution — field changes are additive-only. v0.10.0 added the compliance_status + remediation Optional fields. v0.10.1 introduces Finding as the canonical name alongside SecurityFinding; the SecurityFinding alias is retained for ≥1 minor cycle per the deprecation policy. Target removal of the SecurityFinding alias: v1.0.0 (the earliest major bump). See deprecation-calendar.md. v0.10.5 Phase 10 adds the deterministic-id derivation contract: when a SecurityFinding is constructed with both source_system and source_finding_id present and no explicit id=, the id field derives as uuid5(NAMESPACE_EVIDENTIA_FINDING, f"{source_system}\x00{source_finding_id}"). The NAMESPACE_EVIDENTIA_FINDING UUID is pinned forever (c81bcb44-9b41-5b18-9f10-72b3b9b4d3d6). Two collect() calls against an unchanged source produce findings with byte-identical id values. Per-collector verdicts in collector-idempotency-audit.md.
gap.py GapFinding, GapSeverity, GapAnalysisReport, ControlGap, Milestone, POAMState. v0.9.5 adds Milestone.owner / Milestone.reviewer Optional fields; these are now frozen.
vendor.py VendorProfile, VendorRiskTier
vendor_finding.py VendorFinding
vendor_manifest.py VendorManifest
assessment.py Assessment, AssessmentStatus
claim.py TraceClaim, ReasoningTrace
oscal_profile.py OSCALProfile
catalog.py CatalogEntry, CatalogControl, ControlCatalog, FrameworkMapping, CrosswalkDefinition. v0.10.6 added the CrosswalkDefinition.provenance / verification / verification_note Optional fields (additive-only — backward-compatible, the eight pre-v0.10.6 crosswalks load unchanged).
tprm.py TPRMAssessment, TPRMFinding
governance.py AISystem, AIRiskClassification, GovernanceRecord
ai_governance/classification.py (v0.9.3+) AISystemDescriptor, AISystemClassification, EUAIActTier, NISTAIRMFFunction, AnnexIIIDomain
ai_governance/registry.py (v0.9.3+; v0.9.6 federal expansion) AISystemRegistryEntry, DeploymentStatus, ATOReference (v0.9.6)
ai_governance/fips199.py (v0.9.6+) FIPS199Categorization, FIPS199Impact
ai_governance/omb_m_24_10.py (v0.9.6+) OMBImpactCategory
ai_governance/scr.py (v0.9.6+) SCRForm, SCRCategory
rbac/policy.py (v0.9.5+) Role, RBACPolicy. check_permission(identity, action, policy) + load_policy_from_file(path) callables also frozen.
retention/metadata.py (v0.7.11+) RetentionMetadata, RetentionClassification, RetentionLifecycleStage

Serialization guarantee: JSON-serialized output of any frozen model at version N must be deserializable by version N+1 within the same major. Field ordering in JSON output is not guaranteed.

2. EventAction enum

Package: evidentia_core.audit.events

The EventAction enum is an append-only contract. Existing values are never removed or renamed post-v1.0. New values may be added in any minor release.

Current namespaces (80+ values as of v0.9.8). Example values below are real members of evidentia_core.audit.events.EventAction — the enum module is the authoritative source:

Prefix Domain Example values
COLLECT_* Evidence collection COLLECT_STARTED, COLLECT_COMPLETED, COLLECT_FAILED
AUTH_* Authentication AUTH_CREDENTIAL_RESOLVED, AUTH_CREDENTIAL_FAILED
CONFIG_* Configuration CONFIG_LOADED, CONFIG_RESOLVED, CONFIG_INVALID
SIGN_* Cryptographic signing SIGN_GPG_SIGNED, SIGN_SIGSTORE_SIGNED, SIGN_FAILED
VERIFY_* Verification VERIFY_DIGEST_PASSED, VERIFY_SIGNATURE_PASSED, VERIFY_COMPLETED
MANIFEST_* Manifest operations MANIFEST_GENERATED, MANIFEST_EMPTY_SET_ATTESTED, MANIFEST_INCOMPLETE
AI_* AI/LLM operations AI_RISK_GENERATED, AI_EVAL_FAITHFULNESS_CHECKED
AI_SYSTEM_* (v0.9.3+) AI system inventory AI_SYSTEM_CLASSIFIED, AI_SYSTEM_REGISTERED, AI_SYSTEM_UPDATED, AI_SYSTEM_RETIRED, AI_SYSTEM_DELETED, AI_SYSTEM_FIPS_CATEGORIZED (v0.9.6), AI_SYSTEM_OMB_CLASSIFIED (v0.9.6), AI_SYSTEM_SCR_EMITTED (v0.9.6)
AI_MCP_* MCP server operations AI_MCP_TOOL_AUTHORIZED, AI_MCP_TOOL_DENIED
POAM_* POA&M lifecycle POAM_CREATED, POAM_MILESTONE_REACHED, POAM_VERIFIED
CONMON_* Continuous monitoring CONMON_DAEMON_STARTED, CONMON_ALERT_DISPATCHED, CONMON_CYCLE_DUE, CONMON_CYCLE_OVERDUE, CONMON_CYCLE_MARKED_COMPLETED
EVIDENCE_* (v0.9.6+) Evidence WORM lineage EVIDENCE_VERSION_PERSISTED, EVIDENCE_WORM_VIOLATION_BLOCKED, EVIDENCE_LINEAGE_QUERIED
RBAC_* (v0.9.8+) Multi-tenant RBAC RBAC_TENANT_BOUNDARY_CROSSED
RETENTION_* Data retention RETENTION_RECORD_PUT, RETENTION_RECORD_EXTENDED, RETENTION_LEGAL_HOLD_APPLIED, RETENTION_LEGAL_HOLD_RELEASED, RETENTION_LIFECYCLE_TRANSITIONED, RETENTION_RECORD_PURGED, RETENTION_GDPR_PURGE

Operators building alerting / SIEM integrations on top of the audit log can depend on these values being stable.

3. CLI flag names and semantics

Package: evidentia (the CLI entry point)

Top-level command groups (18+ as of v0.9.7):

evidentia gap          evidentia catalog      evidentia risk
evidentia explain      evidentia integrations evidentia collect
evidentia oscal        evidentia tprm         evidentia model-risk
evidentia governance   evidentia retention    evidentia poam
evidentia conmon       evidentia ai-gov       evidentia eval
evidentia mcp          evidentia serve        evidentia evidence (v0.9.6)

Global flags (frozen across all commands):

  • --verbose / -v — DEBUG-level logging
  • --quiet / -q — ERROR-level only
  • --config <path> — explicit evidentia.yaml override
  • --offline — air-gap guard (v0.4.0)
  • --json-logs — ECS 8.11 JSON output (v0.7.0)
  • --rbac-identity <id> — per-invocation RBAC identity override (v0.9.6)

Stability contract:

  • Command names are frozen (rename = major bump)
  • Flag names (--flag-name) are frozen within each command
  • Flag semantics (what a flag does) are frozen
  • Flag default values may change in minor releases (documented in CHANGELOG)
  • Adding new flags is non-breaking (minor bump)
  • Adding new commands or subcommands is non-breaking (minor bump)

Deprecation for CLI: a deprecated flag emits a DeprecationWarning for at least 1 minor-release cycle before removal. The warning includes the replacement flag name.

4. Plugin contracts

Package: evidentia_core.plugins.*

Five ABC/Protocol contracts that third-party code may implement:

Contract Location Stability
AuthProvider plugins.auth._base Method signatures frozen
StorageBackend[T] plugins.storage._base Generic ABC; method signatures frozen
MarketplaceProvider plugins.marketplace._base Method signatures frozen
BaseSaaSCollector plugins.collectors._base Method signatures frozen; _auth_header() hook stable
ContinuousEvidenceSource plugins.continuous Protocol; poll() + health_check() + attributes frozen

What "method signatures frozen" means:

  • Parameter names, types, and ordering are stable
  • Return types are stable
  • Adding optional parameters (with defaults) is non-breaking
  • Adding new abstract methods to an ABC is a major-bump trigger (breaks existing implementations)

Supporting dataclasses used in plugin signatures are also frozen: AuthResult, CatalogManifest, EvidenceRecord.

5. Library entry points

Public importable paths that operators and integrators use:

# Core analysis + data models
from evidentia_core.gap_analyzer import GapAnalyzer
from evidentia_core.models import ControlGap, GapFinding, ...
from evidentia_core.audit.events import EventAction
from evidentia_core.catalogs.registry import FrameworkRegistry
from evidentia_core.conmon import derive_status, BUNDLED_CADENCES
from evidentia_core.poam import POAMState, Milestone
from evidentia_core.poam_store import save_poam, load_poam_by_id
from evidentia_core.plugins import AuthProvider, StorageBackend, ...

# v0.9.5+ RBAC + collaboration primitives
from evidentia_core.rbac import (
    Role, RBACPolicy, check_permission, load_policy_from_file,
)

# v0.9.6+ evidence WORM store + cloud mirror
from evidentia_core.evidence_store import (
    save_evidence, list_lineage, load_evidence_version,
    list_lineages, get_evidence_store_dir,
    EvidenceWORMViolation, InvalidEvidenceIdError,
    EVIDENCE_STORE_ENV_VAR,
)
from evidentia_core.evidence_store_worm import (
    mirror_to_worm, fetch_from_worm,
)

# v0.9.6+ AI-gov federal expansion
from evidentia_core.ai_governance import (
    FIPS199Categorization, FIPS199Impact,
    OMBImpactCategory, triggers_minimum_practices,
    ATOReference, AISystemRegistryEntry, DeploymentStatus,
)
from evidentia_core.ai_governance.scr import (
    SCRForm, SCRCategory, emit_scr_form, classify_change,
)

# v0.9.6+ OSCAL schema version constant
from evidentia_core.oscal import OSCAL_SCHEMA_VERSION

# v0.10.0+ OCSF Compliance Finding interchange (needs the [ocsf] extra)
from evidentia_core.ocsf import (
    finding_to_ocsf, finding_from_ocsf, OCSFMappingError,
)

# v0.10.4+ Gap-report OCSF Compliance Finding array emit (needs [ocsf] extra)
from evidentia_core.gap_analyzer.ocsf import gap_report_to_ocsf_array

# v0.10.5+ Gap-report OCSF Detection Finding array emit (needs [ocsf] extra)
from evidentia_core.gap_analyzer.ocsf_detection import (
    gap_report_to_ocsf_detection_array,
)

# v0.10.5+ Gap-report CycloneDX 1.6 VEX emit (no extra required)
from evidentia_core.gap_analyzer.vex import gap_report_to_cyclonedx_vex

# AI features (production runtime)
from evidentia_ai.risk_statements import RiskStatementGenerator

# v0.10.5+ DFAH determinism + faithfulness harness (dev-time;
# extracted from evidentia_ai.eval to a dedicated workspace
# package so air-gap installs of the production runtime no
# longer pull the dev-time eval stack). The
# evidentia_ai.eval.* path remains as a deprecation shim
# through v0.11.x; removal scheduled for v0.12.0.
from evidentia_eval import DFAHarness, faithfulness_score

# Collectors + integrations
from evidentia_collectors.vendor_risk import (
    BitSightCollector, SecurityScorecardCollector,
    RiskReconCollector, UpGuardCollector,
)
from evidentia_integrations.alerting import SmtpChannel, WebhookChannel

# API + MCP entry points
from evidentia_api.app import create_app
from evidentia_api.rbac_dependency import require_role
from evidentia_mcp.server import build_server  # v0.8.0+ name

Stability contract: these import paths are frozen. Moving a class to a different module internally is allowed as long as the original import path continues to work (via re-export).

6. REST API URIs

Package: evidentia_api.routes.*

All REST endpoints follow the pattern /api/<resource> and are versioned implicitly (no /v1/ prefix until a breaking REST change necessitates it).

Frozen URI prefixes (16 routers):

Prefix Router module Purpose
/api/health health.py Liveness + readiness
/api/config config.py Configuration state
/api/doctor doctor.py Environment diagnostics
/api/explain explain.py Control explanations
/api/llm-status llm_status.py LLM provider health
/api/frameworks frameworks.py Framework catalog
/api/init-wizard init_wizard.py First-run wizard
/api/risks risks.py Risk statements
/api/gaps gaps.py Gap analysis
/api/integrations integrations.py Integration status
/api/tprm tprm.py Third-party risk
/api/model-risk model_risk.py AI model risk
/api/collectors collectors.py Collector status
/api/metrics metrics.py Prometheus metrics
/api/poam poam.py POA&M management
/api/conmon conmon.py Continuous monitoring
/api/ai-gov ai_gov.py AI governance

Stability contract:

  • URI paths are frozen (rename = major bump)
  • Response JSON field names are frozen (additions only)
  • HTTP methods per endpoint are frozen
  • Query parameter names are frozen
  • Adding new endpoints is non-breaking (minor bump)
  • Adding new optional query parameters is non-breaking

Non-frozen surfaces

These surfaces may change in any release (minor or patch) without constituting a breaking change. Operators should not depend on their stability.

Internal helpers

Any function, class, or module prefixed with underscore (_) is private. This includes:

  • evidentia_core._internal.*
  • Any _helper, _utils, _compat modules
  • Private methods on public classes (def _compute_score(...))

Test fixtures and utilities

Everything under tests/ is non-frozen:

  • Test data files (tests/data/dfah-calibration/corpus*.jsonl)
  • Fixture factories (tests/conftest.py)
  • Test helper modules (tests/helpers/)

Bundled catalog content

The compliance catalogs shipped with Evidentia evolve as authoritative sources publish updates (NIST revisions, ISO amendments, EU regulation enforcement dates). Catalog content changes are patch-level — they don't constitute API breaks.

Explicit version-pinning — via a planned catalog pin <framework> <version> command — is on the roadmap (not yet available).

Threshold defaults

Default values for scoring thresholds (faithfulness, risk determinism, health scoring) may be tuned between releases based on empirical calibration results. These changes are documented in CHANGELOG but are non-breaking because operators can always override via CLI flags:

  • --faithfulness-threshold
  • --faithfulness-threshold-mode {framework-aware,fixed}
  • --fail-on-determinism-rate-below
  • --health-score-weights

Scripts

Everything under scripts/ is operational tooling, not public API. Scripts may be added, removed, or refactored freely.

Docker image internals

The container's internal layout (file paths, installed packages, base image) is non-frozen. Only the CLI interface exposed by the container is stable (same guarantees as CLI flags above).

MCP tool descriptions and metadata

While MCP tool names are frozen (they're part of the tool contract with AI clients), tool descriptions and parameter descriptions may be refined for clarity without constituting a breaking change.

Deprecation policy

When a frozen surface must change:

  1. Announce: add a DeprecationWarning (Python) or deprecation notice (REST response header) in minor release N. Document in CHANGELOG under "Deprecated".

  2. Maintain: the deprecated surface continues to work unchanged for at least 1 full minor-release cycle (release N through N+1).

  3. Remove: earliest removal is in release N+2. Document in CHANGELOG under "Removed". This constitutes a major- version bump.

Example timeline:

v1.2.0 — deprecate --old-flag (warning emitted; --new-flag added)
v1.3.0 — --old-flag still works (warning still emitted)
v2.0.0 — --old-flag removed; major bump

For REST endpoints, deprecation is signaled via:

  • Deprecation: true response header (RFC 8594)
  • Sunset: <date> header when removal date is known

Compatibility testing

The release pipeline validates API stability via:

  1. Type checking (mypy strict): catches signature changes that would break callers
  2. Test suite (2747+ tests): exercises public interfaces against expected behavior
  3. Import smoke test: scripts/check_imports.py (reserved for v1.0) will validate that all documented entry points resolve
  4. Schema regression: Pydantic model .model_json_schema() output compared between releases (reserved for v1.0)

Scope of this document

This document covers the library, CLI, REST, and plugin surfaces of Evidentia. It does NOT cover:

  • The web UI (packages/evidentia-ui/): frontend component APIs are not part of the public contract
  • GitHub Actions workflows: CI/CD implementation details
  • Development tooling: ruff config, mypy config, test infrastructure
  • Documentation format: doc structure may reorganize freely

MCP tool contract

Package: evidentia_mcp.server

MCP tool names are frozen — they are part of the contract with AI clients (Claude Desktop, Claude Code, custom MCP clients). Renaming a tool is a major-bump trigger; adding new tools is non-breaking.

Frozen tool surface (as of v0.9.7):

Tool Since Purpose
list_frameworks v0.8.0 Enumerate bundled catalogs
get_control v0.8.0 Single-control lookup
gap_analyze v0.8.0 Run gap analysis
gap_diff v0.8.0 Compare two gap reports
conmon_list_cadences v0.9.6 List CONMON cadences
conmon_next_due v0.9.6 Compute next-due date
conmon_check_state v0.9.6 Read state file → attention buckets
conmon_health v0.9.6 Health report wrapper
gap_analyze_sarif v0.10.2 Gap analysis + SARIF 2.1.0 output (CI-gate use)
collect_ocsf v0.10.2 OCSF ingestion (file mode only — URL ingest deliberately omitted to harden out the F-V101-L1 SSRF surface)
tprm_vendor_list v0.10.2 List vendors from the local TPRM store (read-only)
poam_list v0.10.2 List POA&Ms from the local store (read-only)
verify_signed_artifact v0.10.4 Verify an Evidentia signed-artifact bundle (*.ar); wraps verify_ar_file with validate_within(--allow-root) path-gating and the standard SignedToolOutput envelope. Returns the OSCAL-bound verification report.

Tool parameter names are frozen. Tool descriptions may be refined for clarity without constituting a breaking change.

CIMD scope-grant semantics (v0.8.5+) are NOT frozen: operators adding new tools through CIMD registry updates (via evidentia mcp cimd-migrate in v0.9.7+) is a deployment-time concern, not an API contract.

Env-var public contract (v0.9.7 NEW)

Operators rely on certain env vars to configure Evidentia at runtime. The names + semantics of these vars are frozen with the same guarantees as CLI flags. Removal requires a deprecation cycle.

Env var Since Purpose
EVIDENTIA_POAM_STORE_DIR v0.9.0 POA&M JSON store directory
EVIDENTIA_AI_REGISTRY_DIR v0.9.3 AI-gov registry directory
EVIDENTIA_TRUST_PROXY_HEADERS v0.9.5 X-Forwarded-For ingest gate
EVIDENTIA_RBAC_POLICY_FILE v0.9.5 (FastAPI), v0.9.6 (CLI) RBAC policy YAML path
EVIDENTIA_RBAC_IDENTITY v0.9.6 CLI RBAC identity
EVIDENTIA_EVIDENCE_STORE_DIR v0.9.6 Evidence store root directory
EVIDENTIA_EVIDENCE_AUTO_MIRROR_WORM v0.9.7 Gate auto-mirror to cloud WORM
EVIDENTIA_EVIDENCE_WORM_BACKEND_FACTORY v0.9.7 Dotted-path factory for auto-mirror backend

Revision history

Version Date Change
DRAFT 2026-05-16 Initial authoring during v0.9.3 P5
DRAFT 2026-05-18 v0.9.4 – v0.9.5 surfaces inventoried (no doc edits yet)
NORMATIVE 2026-05-19 Promoted from DRAFT during v0.9.7 P2.1. v0.9.4 – v0.9.6 surfaces backfilled: evidence WORM store, AI-gov federal fields, FIPS 199 + OMB + SCR models, CONMON MCP tools, OSCAL_SCHEMA_VERSION constant, RBAC primitives, evidence_store env vars. MCP tool contract section + env-var public-contract section added. Pre-v1.0 binding semantics in force.
NORMATIVE 2026-05-22 v0.10.0: models/finding.py joins the frozen-models table (SecurityFinding, FindingStatus, ComplianceStatus) following its additive OCSF-alignment evolution. New evidentia_core.ocsf library entry point (finding_to_ocsf / finding_from_ocsf / OCSFMappingError) added to §5. SARIF is a new evidentia gap output format — non-breaking per §3. See ocsf-mapping.md.
NORMATIVE 2026-05-23 v0.10.1: finding_from_ocsf gains an additive trust_unmapped: bool = True keyword-only parameter (closes F-V100-L1 from the v0.10.0 review). Non-breaking under §1 — additive optional parameter with default. See ocsf-mapping.md §5.1.
NORMATIVE 2026-05-23 v0.10.2: 4 new MCP tools added (gap_analyze_sarif, collect_ocsf, tprm_vendor_list, poam_list) per the MCP-as-backend theme. Append-only per the §MCP tool contract — non-breaking for existing AI clients; the 8 prior tools stay frozen.
NORMATIVE 2026-05-24 v0.10.4: (a) OutputFormat Literal extended with "ocsf" (additive-optional per §3) — evidentia gap analyze --format ocsf emits OCSF Compliance Findings (class_uid 2003), the symmetric counterpart to v0.10.0 SARIF emit + v0.10.1 OCSF ingest; (b) 13th MCP tool verify_signed_artifact added (append-only per §MCP tool contract); (c) evidentia_core.gap_analyzer.ocsf.gap_report_to_ocsf_array new public helper. No removals, no renames, no breaking changes. Reviewed under /pre-release-review skill v5.1 (first ship under v5.1).
NORMATIVE 2026-05-25 v0.10.5 Phases 7+8: OutputFormat Literal further extended with "ocsf-detection" + "cyclonedx-vex" (additive-optional per §3). evidentia gap analyze --format ocsf-detection emits OCSF Detection Findings (class_uid 2004) — SIEM-target counterpart to v0.10.4 Compliance Finding emit (Splunk / Elastic / Sentinel / Datadog ingest 2004 natively). evidentia gap analyze --format cyclonedx-vex emits CycloneDX 1.6 VEX — the supply-chain VEX surface complementing the release-time CycloneDX SBOM emit. Two new library entry points: evidentia_core.gap_analyzer.ocsf_detection.gap_report_to_ocsf_detection_array + evidentia_core.gap_analyzer.vex.gap_report_to_cyclonedx_vex. No removals, no renames, no breaking changes.
NORMATIVE 2026-05-25 v0.10.5 Phase 9: DFAH harness extracted from evidentia_ai.eval.* to a dedicated evidentia-eval workspace package (8th package). Public API moves from evidentia_ai.eval to evidentia_eval (same symbols, same signatures). The evidentia_ai.eval.* path is preserved as a deprecation shim through v0.11.x with a DeprecationWarning at import time; removal scheduled for v0.12.0 (a documented breaking change with a 2-minor-version migration window per §1). The evidentia-ai[eval-faithfulness] extra now proxies to evidentia-eval[faithfulness-semantic] — same packages, new home. Rationale: air-gap installs of the production risk-statement runtime no longer transitively pull the dev-time eval stack.
NORMATIVE 2026-05-25 v0.10.5 Phase 10: Collector idempotency hardening. New evidentia_core.models.common.deterministic_finding_id(source_system, source_finding_id) helper computes a UUID v5 from natural keys under the pinned NAMESPACE_EVIDENTIA_FINDING namespace. A new @model_validator(mode="before") on SecurityFinding runs the derivation when no explicit id= is supplied AND both source_system + source_finding_id are present at construction. Effect: two collect() calls against an unchanged source produce findings with byte-identical id values across runs. Additive-only; explicit id= always wins, OCSF round-trip via unmapped["evidentia"] unchanged, pre-v0.10.5 OSCAL AR documents continue to load. See docs/collector-idempotency-audit.md.
NORMATIVE 2026-05-26 v0.10.6 Phase 1 (commit C1): catalogs. Three new bundled YAML catalogs (osps-baseline-m1.yaml, osps-baseline-m2.yaml, osps-baseline-m3.yaml) bundling the OpenSSF OSPS Baseline at upstream commit ac6bbec (Apache-2.0, Tier-A verbatim). Catalog entries are OSPS assessment-requirements (per-maturity-level applicability filter): M1=25, M2=42, M3=63 (counts verified against upstream tarball; the v0.10.6 plan §Phase 1 expected 21/38/58 — upstream actual is used). Companion OSCAL Catalog 1.2.1 serialization shipped at osps-baseline.oscal.json (8 groups / 41 top-level OSPS controls, mirroring upstream top-level granularity per OSCAL Catalog convention; validated against Trestle 4.0.3 pydantic models). Additive-only per frozen-surface contract — existing 89 catalogs unchanged. scripts/catalogs/regenerate_manifest.py extended with *.oscal.json / *.oscal.yaml skip-filter so OSCAL sidecar artifacts don't register as manifest entries. Manifest count: 89 → 92 frameworks.
NORMATIVE 2026-05-27 v0.10.6 Phase 5 (commit C5): CrosswalkDefinition extended with 3 optional fields — provenance: str | None, verification: Literal["self-attested-via-upstream", "hand-checked"] | None, verification_note: str | None. Additive-only per frozen-surface contract; the existing 8 in-tree crosswalks load unchanged (new fields default to None). 5 new OSPS-Baseline crosswalks land alongside in catalogs/data/mappings/: osps-baseline_to_nist-ssdf-800-218.json, osps-baseline_to_nist-csf-2.0.json, osps-baseline_to_eu-cra.json, osps-baseline_to_pci-dss-4.0.json, osps-baseline_to_nist-800-161.json. Mappings auto-extracted from the OpenSSF OSPS Baseline guidelines[] array at upstream commit ac6bbec; carry provenance="upstream-osps-guidelines" + verification="self-attested-via-upstream". Consumers requiring independent verification should plan a hand-check pass. See docs/v0.10.6-plan.md §Phase 5 + §12.1 for the brainstorm-vs-codebase pre-correction rationale.
NORMATIVE 2026-05-27 v0.10.6 Phase 6 (commit C6): new evidentia_collectors.github.osps module with 16 populate_osps_*(client, owner, repo) -> SecurityFinding helpers covering OSPS-AC/BR/DO/GV/LE/QA/VM family controls via GitHub REST API. Each helper sets compliance_status (PASS/FAIL/WARNING/NOT_APPLICABLE/UNKNOWN) + an osps-baseline ControlMapping plus optional NIST SP 800-53 Rev 5 cross-walk mappings; source_finding_id follows the deterministic osps-<id>:<owner>/<repo>[:<scope>] pattern that feeds the v0.10.5 P10 idempotent-id derivation. Coverage registry exposed as evidentia_collectors.github.osps.OSPS_COVERAGE: dict[str, str]. Additive-only per frozen-surface contract — existing GitHubCollector + DependabotCollector entry points unchanged. GitHubClient extended additively with 4 small probe methods: list_releases, are_vulnerability_alerts_enabled, is_code_scanning_enabled, list_security_advisories. OSPS-VM-05.03 helper is intentionally complementary to the existing DependabotCollector (posture-finding vs per-CVE evidence chain); both emit findings, neither subsumes the other. The 16 OSPS ids covered: OSPS-AC-03.01/03.02, OSPS-BR-06.01, OSPS-DO-02.01, OSPS-GV-03.01, OSPS-LE-02.01/03.01, OSPS-QA-01.01/01.02/02.01/03.01, OSPS-VM-02.01/03.01/04.01/05.03/06.02.

Evidentia wiki

Clone this wiki locally