ADR-043: Standards Mappings Are Published as SARIF Tags¶
Status: Accepted
Context: Every rule cites the sources it is grounded in: CIS Docker
Benchmark controls, OWASP Docker Security Cheat Sheet rules, and the MITRE
ATT&CK techniques its fix mitigates. In SARIF those reached a consumer in two
forms. The CIS and OWASP citations were sentences in the rule's help.text.
The ATT&CK mapping was a taxonomy with a relationship from each rule, added
with ADR-022.
Neither form can be filtered on in GitHub Code Scanning, the consumer most
compose-lint SARIF goes to. Its documentation lists the rule properties it
uses, and relationships and taxonomies are not among them. What it does
use is properties.tags: "Code scanning uses tags to allow you to filter
results on GitHub." Someone who wants every finding that bears on a control
had to keep their own rule-to-control table (#1280).
Facts that shaped the decision:
- GitHub accepts up to 20 tags per rule and includes 10. It does not say which. GitLab's SARIF ingestion keeps 10 per rule by default.
- GitLab gives meaning only to tags shaped like a CWE or CVE identifier, which it uses to choose a report type. Any other tag has no effect there.
- GitHub treats a result as a security result because its rule has a
security-severity. A repository with compose-lint alerts and no tags at all shows a security severity on every alert. - Before tagging, every citation was re-read against its source: the CIS numbers against Benchmark v1.9.0, and each OWASP rule against what the compose-lint rule grades. That found one rule citing the wrong CIS numbers, one citing controls it no longer graded, and two citing an OWASP rule that does not mention their subject. A citation in prose can be loose. A tag cannot, because a filter returns it as a match.
Decision:
- Each SARIF rule descriptor carries
properties.tagswith the rule's CIS controls, OWASP rules and ATT&CK techniques, in that order. - The tag shape is
external/<source>/<id>:external/cis-docker/5.4,external/owasp-docker/rule-3,external/mitre-attack/T1611. This is the shape CodeQL uses for its ownexternal/cwe/...tags, so it is one a Code Scanning user has met. Control and technique ids are written as their publisher writes them. - A CIS tag does not carry the benchmark version. The version is pinned in one constant and stated in the docs. A version in the tag would change every CIS tag at each benchmark revision for anyone filtering on one, including the controls whose number did not move.
- The mapping is data.
compose_lint.standardsholds the CIS and OWASP mapping the waycompose_lint.attackholds the ATT&CK one. A test fails when a rule'sreferencesand the mapping disagree, and a rule with no control from a source is listed with the reason. - The tags are informational, not contract.
ADR-015 already excludes
properties.*beyond the keys it names, and this ADR does not addtagsto that list. A wrong mapping can then be corrected in any release. Adding the tags to the contract later is a loosening no one is harmed by. Taking them out of it later would be a MAJOR. - No
securitytag. It would match every rule, so within compose-lint's results it filters nothing, and it would cost one of ten slots on each rule. Adding it later breaks no one. - No rule may exceed ten tags. A test fails first. Nothing is truncated at run time: which tag a rule gives up is a decision for the change that would add the eleventh.
- The ATT&CK taxonomy stays. It is the more precise form and other consumers can read it. CIS and OWASP are not added as taxonomies: no consumer measured here reads one.
What a tag claims. That the rule relates to the control or technique. Not
that a file with no findings complies with the benchmark: compose-lint reads
a Compose file, and most of the benchmark is about the host, the daemon and
image builds. The standards page says so, in the way attack.py says its
mapping is mitigation coverage and never detection.
Not done:
- CWE tags. GitLab uses one to choose the report type, so adding one can move a project's findings between report types. That is a separate decision with its own consumer to measure.
- The mapping in JSON output. The JSON envelope is contract (ADR-015), so a field added there is one that cannot be corrected freely. No one has asked for it.
- Other frameworks. Each is new mapping work with its own grounding. CL-0031 already has nine tags, so a fourth source does not fit on it without giving one up.
Consequences:
- Alerts can be filtered by control or technique in Code Scanning with
tag:. - Existing alerts keep their identity.
partialFingerprintsis computed from the file, rule, service, evidence and mount target (ADR-024); tags are not an input, and a test holds that. - A new rule adds a row per source, or a reason, in its own PR.
- A benchmark revision means re-reading every cited control against the new text before moving the pinned version.
- A tag people filter on can still change. The changelog records each change, and the docs say the tags are informational.