Skip to content

Commit 041ac9d

Browse files
arpcvgildub
authored andcommitted
Refine SBOM validation process details and update terminology in enterprise contract integration documentation
1 parent 82c7615 commit 041ac9d

1 file changed

Lines changed: 9 additions & 14 deletions

File tree

docs/adrs/00014-enterprise-contract-integration.md

Lines changed: 9 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Enterprise Contract (Conforma) is an open-source policy enforcement tool activel
1616

1717
Users need the ability to:
1818

19-
1. Automatically validate SBOMs against organizational policies
19+
1. Validate SBOMs against organizational policies
2020
2. Define and manage multiple policy configurations
2121
3. View compliance status and violation details for each SBOM
2222
4. Track compliance history over time
@@ -29,6 +29,13 @@ We will integrate Conforma into Trustify as an optional validation service by sp
2929
Validation is manually triggered — not automatic on SBOM upload.
3030
Validation on upload is deferred to a follow-up version.
3131

32+
Uploaded SBOMs start in "Pending" status and are not discoverable until validated. EC validation is one mechanism by which an SBOM can move from "Pending" to "Accepted" or "Rejected":
33+
34+
- An SBOM in "Pending" can be submitted for EC validation.
35+
- A passing EC result transitions the SBOM to "Accepted".
36+
- A failing EC result transitions it to "Rejected", with the violation details linked.
37+
- An EC execution error (CLI crash, policy fetch failure) does not change the SBOM's policy status — the SBOM stays Pending and the error is surfaced separately, so it doesn't silently block an SBOM.
38+
3239
What is stored where
3340

3441
- PostgreSQL: validation status, structured violations (JSONB), summary statistics, foreign keys to SBOM and policy. Indexed on sbom_id, status, executed_at.
@@ -37,18 +44,6 @@ What is stored where
3744

3845
Storing full JSON in S3 rather than only a summary was chosen explicitly to preserve audit completeness — callers can always fetch the raw report. The DB violations JSONB holds enough structure for filtering and dashboards without duplicating the full payload.
3946

40-
### Deferred Validation
41-
42-
I has been decided that uploaded SBOMs start in "Pending" status and are not discoverable until validated.
43-
EC validation is one mechanism by which an SBOM can move from "Pending" to "Accepted" or "Rejected".
44-
45-
Concretely:
46-
47-
An SBOM in "Pending" can be submitted for EC validation.
48-
A passing EC result transitions the SBOM to "Accepted".
49-
A failing EC result transitions it to "Rejected", with the violation details linked.
50-
An EC execution error (CLI crash, policy fetch failure) does not change the SBOM's policy status — the SBOM stays Pending and the error is surfaced separately, so it doesn't silently block an SBOM.
51-
5247
## Consequences
5348

5449
Integrating via CLI spawning rather than a native API introduces an external process dependency that adds operational overhead (Conforma must be installed and version-pinned on every server) and per-validation process spawning overhead. These are accepted trade-offs given that no Conforma API exists yet. The executor is built behind an adapter interface so the implementation can be swapped for a REST client in Phase 3 without changes to the service layer or API.
@@ -271,7 +266,7 @@ sequenceDiagram
271266

272267
### The Data Model
273268

274-
**`ec_policies`** - Stores references to external policies, not the policies themselves
269+
**`ec_policy`** - Stores references to external policies, not the policies themselves
275270

276271
- `id` (UUID, PK)
277272
- `name` (VARCHAR, unique) - User-friendly name label

0 commit comments

Comments
 (0)