Documentation
How to use provenance
A guide to the register, page by page: what each part is for and how to use it, from signing in to publishing a trust statement. For the API, every route and the scope it needs are in /llms.txt.
Getting started
What provenance is
One register for everything an organisation owns and ships: the hardware estate (every device, who holds it, what state it is in) and the software supply chain (every product, release, component and the vulnerabilities that follow from them), joined by deployments so you can tell which software runs on which machine.
It records what you declare and attach. It does not watch your systems. A figure always says what it is counted over, and something nobody has recorded is shown as unknown or not assessed, never as a pass.
Signing in and workspaces
- Choose Sign in. You sign in with your RODMENA identity, and provenance never sees a password.
- You land in your workspace. If you belong to more than one, the workspace switcher in the top bar moves between them, and the register, the counts and the audit trail all change together.
- Your name in the top bar opens Account & plan: your workspace, its plan and usage, and how to upgrade. From there, My access lists your roles and every permission they give you. A role change made by an administrator takes effect the next time you sign in.
The sun or moon button switches between the light and dark themes. Choose Switch account to sign in as someone else, and Sign out when you are done.
Open “Signing in and workspaces” in provenance
The overview
This is the first page after signing in. Each tile is a count with the population it is counted over, and most tiles link to the filtered list behind them: assets in service, unencrypted endpoints, findings not yet assessed and whether the audit chain verifies. A tile in amber or red needs attention. A zero is not a link, because there is nothing behind it.
Hardware
Registering and tracking assets
- Choose Register an asset and give its tag, category and the facts you have. A registered asset enters stock.
- Record what happens to it as events on its page: assigned to a custodian, returned, sent for repair, recorded lost. Each event is kept, and the register holds the asset's whole path as well as its current state.
- If a fact was recorded wrongly, use Correct a recorded detail and give a reason. The previous value and your reason go into the audit trail.
- Attach evidence files such as screenshots, receipts and certificates to the asset. They are stored encrypted and served only to people who may read the asset.
Disposal is irreversible and relevant to Cyber Essentials. It has its own page and needs an approval. Held by, which you reach from the custodian's name on an asset's page, lists everything a person has not returned, including kit out for repair. Open it when someone leaves. As of a date shows the inventory exactly as it stood at the end of that day.
Open “Registering and tracking assets” in provenance
A device’s Cyber Essentials pages
Each asset links to its Cyber Essentials pages: whether it is in scope and why, its firewall rules with the business need and approval behind each, the updates it still has to install and the software installed on it, and its answer to each device requirement. A requirement with no answer is shown as not assessed, never counted as met.
Hardware bills of materials
A hardware bill of materials (HBOM), as CISA’s HBOM Framework (2023) defines it, is a vendor’s document about a hardware product: the parts inside it, the companies that made them and where. provenance attaches it to a hardware model, and the devices in the asset register are instances of a model, so fifty identical laptops share one HBOM. The asset register itself is unchanged.
- Register the model on Hardware models, or take a suggestion: Suggested models groups devices that have no model by the make and model the register holds for them.
- Record the vendor’s HBOM on the model’s page: CycloneDX as JSON, or the CISA fields as CSV or JSON. The CSV template is on that page. With no vendor document, declare from the label what your organisation read off the device; it is shown as declared by you, weaker evidence than the vendor’s.
- Link each device to its model, from the device’s page or all at once from a suggestion. Each link keeps its reason.
Coverage shows how much of the hardware in use has an HBOM, and how much of what each CISA use needs those documents state. Supply-chain exposure answers which devices contain parts made in a place or by a company, through sub-assemblies to the products that contain them. Concentration groups the parts by country or company. Every answer carries what could not be checked across the whole register, because a zero is only as good as that.
On a paid plan, an administrator can screen HBOMs against the organisation’s own restricted lists; provenance ships none. A match is for review and a person records the decision, never a legal finding: an HBOM is not proof of compliance. ISO 27001 A.5.21 in the evidence pack reads all of this.
Software
Products, releases and SBOMs
- Register a product. Its slug is the stable name every release, SBOM and evidence pack refers to.
- Publish releases from your build pipeline with an API key that holds release_write and sbom_publish. Create the release, then send its CycloneDX SBOM to it. The routes and scopes are listed in /llms.txt.
- Each release page shows what it ships and the findings that follow from it. A published SBOM is never edited. If one is wrong, record a correction, which says so without touching the original.
Open “Products, releases and SBOMs” in provenance
Finding who ships a component
Components are deduplicated by package URL across the whole estate. When an advisory lands, search for the component here. One row tells you every product and release that ships it, and whether it is deployed.
Open “Finding who ships a component” in provenance
The cryptographic inventory and quantum readiness
Publish a CycloneDX document with cryptographic-asset components (a CBOM), alone or inside the SBOM, to a release in the usual way (POST /api/v1/releases/{release_id}/sbom). We classify every algorithm, certificate, protocol and key in it against NIST SP 1800-38B. What the document claims about its own safety is not taken on trust, and a claim we do not grant is marked “Claim overridden”.
- Quantum-vulnerable: a public-key algorithm Shor’s algorithm breaks (RSA, DH, ECDH, ECDSA, EdDSA, DSA). Hybrid: classical and post-quantum together. Quantum-resistant: ML-KEM, ML-DSA, SLH-DSA, LMS/XMSS. Not in quantum scope: symmetric ciphers and hashes. Not identified: never counted as safe.
- A protocol is judged twice: key exchange (recorded traffic can be decrypted later) and authentication (signatures and certificates). “Classically weak” is a separate flag for things weak even today, such as MD5 or RSA under 2048 bits.
- Quantum readiness starts with coverage: how many releases, and how many deployed releases, were actually analysed. Then the counts, the priority list (every score shows its reasons), where each algorithm family is used, progress over time, and expiring certificates.
- Every count opens the filtered list, and the list’s address is the API’s filter: the same filters download as CSV. A release page shows its cryptography, compares it with another release, and downloads its CBOM.
- Certificate expiry alerts (paid plans) mail the alert recipients 30 and 7 days before a certificate expires. Settings › Alerts keeps the record and previews the next run.
The routes and their scopes are listed in /llms.txt under “cryptography”.
Open “The cryptographic inventory and quantum readiness” in provenance
Recording deployments
Record which release runs in which environment, on which machine and since when. This join separates an incident (a vulnerable release that is live) from a backlog item (the same release that nobody runs). Withdraw a deployment when it stops running.
Open “Recording deployments” in provenance
Licence policy and pipelines
Licence policy lists every licence declared by a component in the estate with the verdict recorded for it. Pipelines shows the scheduled runs (the vulnerability rescan and the alert dispatch) and the evidence that each one ran. A night that did not run leaves a failed row, never a missing one.
Security
Triaging findings and VEX
- Open Findings & VEX. Findings are sorted by severity, and the Deployed column decides urgency.
- Filter by product, severity, or to deployed or unassessed findings only.
- On a finding, record a VEX position (affected, not affected, fixed or under investigation) with the reasoning. A machine can propose a position, but only a person can approve one.
Open “Triaging findings and VEX” in provenance
Security alerts
Security alerts is the ledger of what was actually sent to a person and when. It shows that an alert was not silenced. Choose where alerts go under Alert recipients. An address receives nothing until it has confirmed itself.
Compliance
Cyber Essentials
Answer the organisation-wide requirements once, with the evidence behind each. Device requirements are answered on each asset's own page. The answer sheet gathers every question, approved apps covers employee-owned devices, and CE Plus tests records what the assessor tested and found, with the files behind each result.
Open “Cyber Essentials” in provenance
ISO 27001 registers
The ISMS pages hold the ISO 27001 registers beside the evidence: risks, policies, incidents, backup and revocation tests, access reviews and requests, suppliers, the workforce, acknowledgements, training, exercises, inherited controls and certifications. The Statement of Applicability records each Annex A control, whether it applies, why and how, and nothing in it is pre-filled. Trust coverage shows what each trust control rests on and what is missing.
Open “ISO 27001 registers” in provenance
Approvals
Who approved what, in their own words, when and from which source. Records that need an approval (a disposal, a policy, an access request) link to one here. Nobody records their own approval by typing it.
Open “Approvals” in provenance
Exporting evidence
Evidence export builds a control-tagged pack for an assessor: each section states what the register evidences and what it does not. Every evidence export is recorded in the audit trail with the digest of the bytes produced. SBOM export produces one CycloneDX document for everything deployed across the estate.
Open “Exporting evidence” in provenance
Publishing a trust statement
- An administrator sets the public header: the organisation’s name, a role address for security contact, and optional website and privacy links.
- Open Preview to see exactly what would be published, its fingerprint (SHA-256), anything left out and why, and anything blocking publication.
- Request approval. A different member (an administrator or a security officer) opens the request, reads the same content, ticks that it names no individual and approves. It is then signed and published. You cannot approve your own request.
- Each published statement shows whether its bytes are intact and its signature valid, and offers a letter as a page or a PDF. Withdraw it with a reason when it should stop being served. Rotating the public link withdraws it too.
Open “Publishing a trust statement” in provenance
The audit trail
Every change is appended to a hash-chained log. Each entry stores the digest of the one before it, so altering or removing a historic row breaks the chain, even when the change is made directly in the database. Filter by the kind of record or by a record's id. Each record page also links to its own entries. The page shows how to recompute the chain yourself.
Administration and automation
Your account and plan
Account & plan (your name in the top bar) shows who you are, the workspace you are working in and how much of its plan that workspace uses: assets, products, releases, API keys, members and evidence storage, each against its limit. A plan sets how much can exist at once and how much can be done each day, such as SBOM ingests, scans and PDF exports, with daily allowances reset at 00:00 UTC. At a limit, the action is refused with the limit named, and the message says when a daily allowance resets. The free plan leaves out nightly rescans, alert emails, running pipelines on demand and publishing a trust statement.
To get more, choose Contact sales about upgrading. The message already names your workspace and its usage. You can compare plans on the pricing page.
Open “Your account and plan” in provenance
Roles, members and erasure
Access model shows which permissions each role gives and which actions a machine may never perform. A workspace administrator invites people and sets their roles under Members, and roles are held per workspace. Erase a person removes the link between someone and what they did without rewriting the audit trail. It cannot be undone.
Open “Roles, members and erasure” in provenance
API keys for your pipelines
- Under API keys, choose Issue an API key, pick only the scopes the system needs, and set an expiry (at most a year).
- Copy the secret when it is shown. Because it is shown once and stored only as a digest, a lost key has to be revoked and reissued.
- Use it as Authorization: Bearer <key>. GET /api/v1/whoami tells any credential what it may do, and /llms.txt lists every route with the scope it needs.
A key cannot approve a VEX position, dispose of an asset, change policy or acknowledge an audit-chain break, whoever holds it, administrators included.
Help
Getting help
- A question about using provenance: write to support@rodmena.co.uk.
- A security vulnerability: follow /.well-known/security.txt, or see Security & trust.
- An accessibility barrier: the accessibility statement says what has been tested and how to tell us.