Concepts and methodology

The canonical reference for every term, score and dimension the engine produces. If a number or flag appears in a report, its meaning and its limits are defined here.

1 · The component model

Every scanned item is a component with these fields:

FieldMeaning
ecosystemnpm (package-lock, pnpm-lock, bare package.json) · PyPI · Maven/Gradle (incl. Android) · Cargo (Rust) · NuGet (.NET) · Go · OCI (container images) · GitHub Actions · AI Model
relationdirect (you chose it) · transitive (a dependency of a dependency) · declared (listed in a bare requirements.txt — the transitive tree is invisible)
introduced_viafor transitive components: the direct dependencies through which it enters. The actionable fact — you fix transitive risk at the entry point.
depthdistance from your project in the dependency graph (informational only — risk is never discounted by depth; xz-utils was deep)
scoperuntime (ships in your product — the CRA's concern) · build (runs in your pipeline: Actions, base images, AI coding tools — a compromised one injects anything into what ships)

2 · The jurisdiction vector

"Jurisdiction" is four different questions. The engine answers each separately:

DimensionFieldQuestionSource
Legal controljurisdictionWhose law can compel the entity holding the project?Curated organization registry, GLEIF legal-entity records, maintainer profile signals
Distributiondistribution_jurisdictionWhose law controls the registry the artifact transits?Constant per ecosystem — npm (Microsoft), PyPI (PSF), Go proxy (Google) are all US. 100% coverage, zero inference.
HostinghostingWhere does the source of truth live?Host domain (github.com → US; codeberg.org → DE e.V.)
OS packaging (C/C++ only)distro_vendor_jurisdictionWhose law reaches the vendor that builds/patches/signs the OS package a project actually links?Curated per --reference-distro target — the distro/ports vendor, not the library author. Only populated when a reference distro is set at scan time.
Maintainer geography(feeds jurisdiction)Where do the humans sit?Maintainer profile locations, bucketed to country groups

They routinely diverge — EU-authored code is still US-distributed. Sovereignty scoring uses legal control; distribution is reported alongside so the headline stays truthful.

Buckets: US · EU (the 27) · UK/adequacy (UK plus GDPR-adequacy jurisdictions: CH, NO, CA, JP, KR, IL, NZ…) · CN · Other (a known country outside those, i.e. the rest of the world) · Unknown (no signal at all).

Why legal control matters: CLOUD Act & FISA §702

Legal control isn't an abstract label — it determines who can be compelled. Two distinct US authorities, two distinct exposure classes, both derived from the signals above:

AuthorityReachesSovra's proxy
CLOUD Act (18 U.S.C. §2713)Any US-controlled provider — extraterritorially, regardless of hostingjurisdiction == "US" (the legal-control signal, this section)
FISA §702 (50 U.S.C. §1881a)Specifically US "electronic communication service" / "remote computing service" providers — a narrower classDeclared AI-toolchain providers (§5) and their jurisdiction

This is a risk lens, not a compliance obligation — there is no "CLOUD Act compliance" a vendor achieves, unlike CRA/NIS2/DORA/AI Act above. It is exported as its own ontology framework (USEXPOSURE, two provisions: USEXPOSURE-CLOUDACT served by the jurisdiction check, USEXPOSURE-FISA702 served by AI-toolchain provenance) via sovra export --framework usexposure or the UI's Regulatory mapping panel. Provider "covered" status, government process and privilege determinations require counsel — this surfaces the exposure signal, not a legal opinion.

Confidence on jurisdiction

Every legal-control value carries a confidence score (0–1). It is inferred intelligence, never asserted fact, ordered by evidentiary strength:

SignalConfidence tierNote
Curated organization record (Microsoft, Eclipse AISBL…)Highverified legal seats
GLEIF legal-entity recordHighopen LEI database; conservative entity matching
Maintainer profile locationLowself-declared free text, bucketed by jurisdiction; can go stale unnoticed
No signalBaselinereported Unknown — never guessed

Corroborating signals increase confidence up to a ceiling; conflicting strong signals (e.g. US legal entity, EU maintainer base) produce disputed: true and reduce confidence — a conflict is a *finding*, not something to average away.

Known limit: commit-timezone analysis is impossible via the GitHub API (dates are normalized to UTC); it would require cloning. Not implemented rather than implemented badly.

3 · Risk flags

FlagTriggerWhy it matters
singleactive maintainers ≤ 1one person is the supply chain — the xz-utils pattern (compromise or abandonment of one individual)
staleno maintainer activity over an extended periodsecurity fixes unlikely to arrive
relicenselicense family with restrictive-relicensing history (Elastic-2.0, BUSL, SSPL)redistribution terms can change under you; CRA-relevant
handoffdocumented maintainer-handoff / compromise history (curated)the tj-actions/changed-files compromise
unpinnedGitHub Action not pinned to a 40-char commit SHA, or image tagged :latestmutable refs are rewritable by an attacker — the tj-actions/changed-files compromise (March 2025)
us-distributionscan-level finding: majority of runtime artifacts transit US-controlled registriesthe registries are a choke point regardless of authorship. Flagged once at scan level (per-component flagging would be noise); the mitigation is an EU-controlled pull-through mirror — a configuration change, not a code change
centralized-distributioncomponent is distributed exclusively through a vendor-controlled mobile platform (Google/Apple/Huawei/Xiaomi/Samsung)the vendor acts as a gatekeeper and can retroactively block app installation (e.g., Google's Sept 2026 Android developer verification); creates single-point-of-failure and lock-in risk
fresh_releasethe resolved version was published inside the recent release cooldown windowa bad or hijacked release is usually caught within days; a very new one has had no time to be. Needs last_release_date; unknown never flags. Scored on build components only
unpinned_upstream_cithe upstream repository's OpenSSF Scorecard *Pinned-Dependencies* check indicates unpinned dependenciesits own CI pulls mutable dependencies. Not-applicable checks are treated as unknown and never flag. Scored on build components only
dangerous_workflowupstream Scorecard *Dangerous-Workflow* check indicates workflow riskits CI has a script-injection or untrusted-checkout pattern. Not-applicable checks are treated as unknown. Scored on build components only
abandonment-riskconcentration is single or dominant and activity_status is slowing or staleconcentrated *and* cooling off at the same time. Purely informational: it does not alter numerical scores

Active maintainers — the approximate number of people actively maintaining the component, derived from committer distribution (DDS or a single committer). This is the term used everywhere in the product and the reports; the machine-readable field is named bus_factor (kept for API stability). n/a means *no data*, which never silently becomes a flag.

Maintainer concentration — raw headcount and work concentration answer different questions, so the engine reports both separately:

FieldMeaning
contributorsraw committer headcount, capped at 99 (contributors_capped: true marks the cap — "99+" in the UI)
concentrationsingle (only one contributor exists) · dominant (one person does nearly all the work even though others contribute) · spread (neither) · null when there's no data

The UI renders the pair as e.g. "1 of 40 · dominant" (40 people touch the code, one does nearly all of it) versus "1 · solo" (there is truly only one person) — two different risk profiles.

Activity dates — last_activity_months (derived from upstream maintenance signals) is paired with last_release_date, the publication date of the version a dependency actually resolves to. Either can be null ("unknown", never guessed) when the underlying source doesn't cover the component (e.g. C/C++ libraries with no central registry). activity_status classifies maintenance cadence into active · slowing · stale · unknown.

4 · Scores (all 0–100, higher better)

Sovereignty — evaluates origin exposure combined with legal control and licensing governance across all components (with runtime components weighted more heavily than build-scope components). Every persisted or returned scores dict carries a scoring_version marker so policy gates and trend charts remain consistent across methodology revisions.

Resilience — runtime components only. Starts from 100 and deducts penalties for runtime concentration, staleness, handoff history and pinning risks. Unknown activity is never scored as a penalty by itself, while known risk flags always count. When activity is known for too few runtime components the score is withheld: scores.resilience is null and scores.scores_status.resilience is "insufficient_data" (shown as "insufficient data"; a min_resilience policy gate fails closed with a message saying why).

Build hygiene — build components only. Starts from 100 and deducts penalties for unpinned build steps, single-maintainer or stale build tools, handoff history, fresh releases, upstream CI weaknesses, and missing release provenance. 100 when there is no build chain. Release provenance and upstream-hygiene checks count only known data: an unknown value adds no penalty and lowers only analysis confidence. See Release provenance.

Analysis confidence — how much to trust the three scores above. Combines five data-completeness signals:

SignalMeaning
Provenance coverageshare of components enriched with KB/pipeline intelligence
Mean jurisdiction confidenceaverage confidence across resolved components (§2)
Maintainer-data availabilityshare with active-maintainer counts (bus_factor)
Activity-data availabilityshare of runtime components with a known activity or release date
Tree visibilityshare *not* from declared-only manifests

Low confidence means the scores are floors/estimates, not verdicts — run sovra kb warm to raise coverage. An empty scan (0 components) has confidence 0 and an explicit warning — nothing-measured must never present as all-clear. Unpinned requirements appear with version ?: visible beats invisible.

Floor vs ceiling. The US share is reported as a range: the confirmed floor, and the ceiling if every Unknown resolved to US (us_share_ceiling_pct). Bounds instead of false precision.

5 · AI-generation provenance (declared tier)

LLM coding tools are build-chain suppliers: they shape the code and see the prompt context (your code goes *into* the model). The engine models a detected provider as a scope: build component of ecosystem AI Model, with the provider entity's legal seat as its jurisdiction (Anthropic/OpenAI/ Google = US, Mistral = EU…).

What jurisdiction does generated code itself have? Almost none — purely AI-generated output is most likely not copyrightable (human-authorship requirement, US and EU); ownership rests on the provider's contract, under the provider's governing law. Those are the facts the engine reports.

Detection tiers — only the first is implemented, by design:

TierEvidenceStatus
declaredagent config files (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursorrules, .windsurfrules, .aider.conf.yml) · AI co-author commit trailers✅ implemented
inferredstatistical style detection❌ not implemented — unreliable arms race; violates "reported, never guessed"
attestedCycloneDX ML-BOM / AI provenance attestationsfuture — coverage will arrive with AI-Act transparency obligations

Declared evidence proves the *tool is used*, not which lines it wrote. ai_commit_pct = share of sampled commits carrying an AI co-author trailer.

Release provenance & upstream hygiene

Computed from upstream package and repository metadata fetched during KB enrichment. Three optional fields on each enriched component; absent or null means *unknown*, never *false*:

FieldMeaning
provenance{verified, types, source_repo} when upstream registries list attestations (npm: SLSA, PyPI: PEP 740). verified is true only if every listed attestation is verified; present-but-unverified reads as not verified. {verified: false, types: [], none_published: true} when none are listed. null when metadata is unavailable or for ecosystems without registry attestations
last_release_dateupstream version publication date, used to compute release_age_days
upstream_hygiene{Pinned-Dependencies, Signed-Releases, Token-Permissions, Dangerous-Workflow, Branch-Protection: 0-10 or null} from OpenSSF Scorecard

provenance_verified and no_provenance are signals (dependency.signals), not flags: no_provenance describes most of a dependency tree and does not trip the "flagged component" logic of the policy gate, history diffs or dashboards. They show in the report's *Release provenance* line and in the SBOM as sovra:provenance (verified | unverified | none) and sovra:release-age-days.

6 · The knowledge base (KB)

Four resolution tiers, consulted in order:

1. Curated seed — hand-verified entries covering major foundations, organizations and providers. Highest trust. 2. Pipeline cache (populated by sovra kb warm or inline with sovra scan --warm; scans from the web app always do this). The scanner follows every referenced package — direct and transitive alike (lockfiles enumerate the full tree) and resolves each package's license and jurisdiction provenance from public registries and entity databases (deps.dev, ecosyste.ms, GLEIF). Missing sources lower confidence, never fail. 3. Namespace heuristic tier (Maven only): reverse-domain groupIds provide a baseline jurisdiction signal (e.g. org.eclipse → EU; de.* ccTLD → EU). Jurisdiction-only — deliberately not counted as full provenance coverage until warmed. 4. Unresolved → Unknown at baseline confidence. Counted against coverage.

7 · Outputs

8 · Continuous monitoring (snapshots, diff, gate)

Each scan snapshot is stored per repository; diff compares the latest two and marks changes material when a new flag appears, a flagged component enters, a component disappears, or jurisdiction moves. The gate evaluates a JSON policy: static rules (min scores, forbidden flags/jurisdictions, US-distribution cap) plus the baseline rule (forbid_new_flags) that fails only on NEW risk — accepted debt stays accepted. Exit codes: 0 pass, 1 violations, 2 usage error.

Snapshot time proof (the day proof)

Each tenant's snapshots of a UTC day are hashed into one Merkle tree and the root gets one timestamp (RFC 3161). Once the day is stamped, every snapshot record Sovra serves (history, API, export, CLI) carries its own proof in a dayProof field beside the signature bundle, so anyone can check "existed no later than <TSA time>" with no database and no tenant context.

``json { "repo": "acme/app", "...": "...", "signature": { "...": "a plain Sigstore bundle, no Sovra field inside" }, "dayProof": { "date": "2026-11-09", // the UTC day the snapshot joined "index": 2, "size": 3, // leaf position and number of leaves "path": ["<hex sha256>", "..."], // RFC 9162 audit path "root": "<hex sha256>", // the Merkle root the TSA signed "signedTimestamp": "<base64 DER>" // RFC 3161 token over root } } ``

The proof lives in the record, never inside the bundle: cosign parses bundles strictly and refuses any unknown field, so the bundle stays a plain Sigstore bundle that cosign verify-blob-attestation and sovra extract read unchanged. A verifier takes the leaf sha256(0x00 || DSSE payload bytes), checks it against root with path (RFC 9162), then checks that the token covers root and chains to a configured TSA root. size is informational (root, path and index bind the claim). dayProof is not signed content: sovra verify and /api/verify set it aside before comparing the record with the signed predicate.

A proof that fails either check is refused; it is never replaced by the ledger. A record without dayProof (served before its day was stamped) falls back to the tenant's ledger.

9 · Multi-tenancy

Tenant API keys are generated once and stored only as SHA-256 hashes. Data boundaries: private per tenant — scans, snapshots, diffs, policies and dashboards; shared — the KB cache (public package intelligence only; no customer data ever enters it). The platform dashboard (owner keys only) is anonymized by construction: distributions, prevalence and public package names — never tenant or repo identifiers.

10 · Privacy & honesty rules (design invariants)

11 · Glossary, acronyms & reference incidents

Every acronym Sovra uses, in plain language, with a link to the authoritative source. Knowing exactly what a term means — and being able to check it — is itself part of the confidence the tool is meant to give you.

Regulations & legal frameworks

AcronymFull nameWhat it requires (in one line)Source
CRA EU Cyber Resilience Act — Regulation (EU) 2024/2847A machine-readable SBOM (at least top-level dependencies), secure-by-design, and vulnerability reporting for any product with digital elements. Reporting obligations apply 11 Sep 2026; full obligations 11 Dec 2027.EUR-Lex 2024/2847 · EC overview
NIS2 Network & Information Security Directive 2 — Directive (EU) 2022/2555Baseline cybersecurity risk-management and incident-reporting duties across essential/important sectors, explicitly including supply-chain security. Unlike every other framework in this table, it's a Directive: it binds only through each Member State's own transposing law, which varies in entity thresholds, sector scope and sanctions. sovra compliance --country <cc> cites the curated national delta where one exists or an explicit not-yet-curated warning — never the Directive text presented as if it were the national law.EUR-Lex 2022/2555
DORA Digital Operational Resilience Act — Regulation (EU) 2022/2554ICT risk management for EU financial entities; Article 28 requires a continuously maintained register of ICT third-party providers — the "what's in our stack, always" view.EUR-Lex 2022/2554
EU AI Act Artificial Intelligence Act — Regulation (EU) 2024/1689Risk-based rules for AI systems. Relevant here because Annex IV technical documentation for high-risk systems must describe third-party software, pre-trained models/tools used (2(a)), software versions (1(c)) and component architecture (2(c)); Art 25 assigns value-chain responsibilities and Art 53 covers integrated general-purpose AI models. Sovra populates that component/AI-toolchain slice — not risk classification, data governance, human oversight or conformity assessment. Phased application: GPAI 2 Aug 2025, high-risk (Annex III) 2 Aug 2026, high-risk (Annex I) 2 Aug 2027.EUR-Lex 2024/1689 · Annex IV
GDPR General Data Protection Regulation — Regulation (EU) 2016/679EU personal-data law. Relevant here because maintainer geography touches personal data — Sovra stores only derived country buckets, never dossiers.EUR-Lex 2016/679
CLOUD Act US Clarifying Lawful Overseas Use of Data Act (2018), codified at 18 U.S.C. §2713Lets US authorities compel US-controlled providers to produce data regardless of where it is hosted — why US legal control matters even for EU-hosted artifacts. Formalized as the USEXPOSURE-CLOUDACT provision (§2 above, exportable via sovra export --framework usexposure).US DOJ
FISA §702 US Foreign Intelligence Surveillance Act, Section 702 — 50 U.S.C. §1881a; last reauthorized by the Reforming Intelligence and Securing America Act (RISAA), 20 Apr 2024Compels US "electronic communication service" / "remote computing service" providers to assist with foreign-intelligence targeting — a narrower provider class than the CLOUD Act's general reach. Formalized as the USEXPOSURE-FISA702 provision, evidenced by declared AI-toolchain providers (§5). Sovra cannot determine whether a given provider is actually "covered" under a §702 certification — that needs counsel.Cornell LII, 50 U.S.C. §1881a

Standards, formats & data sources

TermWhat it isSource
SBOMSoftware Bill of Materials — a machine-readable inventory of every component in your software.CISA
CycloneDXThe OWASP SBOM standard Sovra emits (v1.6).cyclonedx.org
SPDX An alternative ISO/IEC 5962 SBOM format (not yet emitted; on the roadmap).spdx.dev
purl Package URL — the pkg:npm/lodash@4.17.21 coordinate scheme used in the SBOM.purl-spec
GLEIF / LEI Global Legal Entity Identifier Foundation and its open Legal Entity Identifier database — used to resolve who legally controls a project.gleif.org
OIDC / Sigstore OpenID Connect — the identity protocol behind Sigstore/cosign keyless signing (a short-lived identity instead of a long-lived key).Sigstore · OpenID Connect
Ed25519The fast elliptic-curve signature scheme used for Sovra's key-based signing. Pinned partner keys may also be ECDSA P-256 (NIST curve, FIPS 186-5), for verification.ed25519.cr.yp.to
PEP 621The Python standard for project metadata in pyproject.toml ([project] dependencies).peps.python.org/pep-0621
Scorecard OpenSSF Scorecard — upstream repository security checks used for maintenance and CI-hygiene signals.OpenSSF Scorecard
DDS Development Distribution Score — from ecosyste.ms, measuring how concentrated commits are across contributors; high concentration signals an effective single maintainer.ecosyste.ms

Reference supply-chain incidents

These two real incidents are the patterns the resilience and build-hygiene scores are designed to catch. The flags reference them by name; here is the context.

The xz-utils backdoor — CVE-2024-3094

In March 2024 a backdoor was discovered in xz-utils (the liblzma compression library shipped on virtually every Linux distribution). It was not a coding bug: over roughly two years a contributor operating as "Jia Tan" earned the trust of the project, was granted commit and then release-manager rights, and shipped malicious code in versions 5.6.0 and 5.6.1 that targeted the sshd daemon for pre-authentication remote code execution. It was caught almost by accident by a Microsoft engineer (Andres Freund) investigating a ~500 ms SSH slowdown. This is the canonical case for three Sovra flags at once: a deep dependency, a single maintainer, and a maintainer handoff. Sources: Wikipedia · NVD CVE-2024-3094.

The tj-actions/changed-files compromise — CVE-2025-30066

In March 2025 the widely used GitHub Action tj-actions/changed-files was compromised. Attackers retroactively repointed many existing version tags (e.g. @v44, @v45) to a single malicious commit that dumped CI/CD secrets — access keys, tokens, private keys — into public workflow logs. Over 23,000 repositories referenced the action; anything using it between 12–15 March 2025 was at risk. It was patched in v46.0.1. This is exactly why Sovra raises the unpinned flag: a mutable tag is rewritable by whoever controls the upstream, so actions must be pinned to a full 40-character commit SHA. Sources: CISA alert · GitHub Advisory GHSA-mrrh-fwg8-r2c3.

12 · Open-source license compliance

A separate legal axis from sovereignty and security. Sovereignty asks *who controls this dependency*; license compliance asks *what does using and distributing this code obligate us to do, and do any obligations conflict*. The reference standard is OpenChain ISO/IEC 5230:2020 — a process standard for an organisation's OSS compliance programme. Sovra performs the technical steps (identify the OSS, resolve obligations, prepare notices) and evidences the programme; it cannot make an organisation "5230 conformant" — that is a programme attestation, not a tool output.

License identification

Each component's raw license string is normalised to a canonical SPDX id (or SPDX expression like MIT OR Apache-2.0). Aliases ("Apache 2.0") and deprecated ids (GPL-2.0 → GPL-2.0-only) are mapped; anything unresolved is reported as unknown with the original string kept — never silently dropped. For a dual OR license the choice is surfaced, defaulting to the most restrictive option until a choice is recorded (fail-safe, not fail-permissive).

Obligation class

Every license carries an obligation class and tags:

ClassExamplesCore obligation
permissiveMIT, BSD, Apache-2.0Attribution / notice on distribution
weak-copyleftMPL-2.0, LGPL, EPLDisclose source of the (modified) library
strong-copyleftGPL-2.0, GPL-3.0Offer complete corresponding source, same license
network-copyleftAGPL-3.0, SSPLSource obligation triggers on network use
source-availableBUSL, Elastic-2.0, SSPLField-of-use / commercial restrictions
public-domainCC0, Unlicense, 0BSDNone

Reach

An obligation only matters if it actually attaches to how you ship. Reach combines the class with the project's distribution mode and the component's scope:

This is why a GPL build tool, or GPL under SaaS, costs nothing, while distributed strong-copyleft and network-exposed AGPL are weighted heavily. Static vs dynamic linking (which narrows some LGPL obligations) cannot be detected from a manifest — it is a property of the build/link step, so Sovra models at scope granularity and flags the limitation rather than guessing.

C/C++: declared direct deps + curated transitive

C/C++ has no central registry or lockfile, so a build manifest (ffmpeg-style configure, vcpkg, Conan) lists the libraries the project links directly, without versions and without each library's own dependencies. Sovra treats those as direct deps, fills their license/jurisdiction from a curated knowledge base (the verifiable signal is the license — e.g. x264/x265 are GPL), and expands a curated transitive map of well-established sub-dependencies (e.g. librsvg → cairo, gnutls → nettle, gmp). That transitive layer is best-effort "typically links" knowledge, not resolved from a lockfile — build flags can prune it — so it is presented like jurisdiction: curated intelligence, not a guaranteed resolved tree. Versions stay ?; the confidence score reflects the declared, registry-less nature of the ecosystem.

License-risk score & flags

The license score (0–100) evaluates obligation reach over runtime components, with an additional penalty for any unresolved incompatibility. Flags: copyleft (live source-disclosure obligation), license-conflict (incompatible with another component — a distribution blocker), license-unknown (unresolved license). Conflicts use a curated set of well-established incompatible pairs (e.g. GPL-2.0-only with Apache-2.0) and are only raised among components whose obligations are actually live under the chosen mode. The OpenChain export pack (sovra export --framework openchain) renders the BOM, the obligation register, the conflict report and a generated NOTICE file; copyright lines absent from the knowledge base are marked [VERIFY], never fabricated.