IF Commons GitHub

Findings: what a finding is

0002Active

0002-findings-model · owner if · domain commons

Requirements

FR-001checkpassing

A finding MUST have a rule, a title, a severity (critical, high, medium, low or info), the asset it is about, a description, the weaknesses (CWE) and vulnerabilities (CVE) it names, and where it was read from (the tool, its version where known, and the file); it MAY have a place on the asset, a solution and a piece of evidence.

Enforced (check): .github: cd commons/findings && bun run verify — suite/model.test.ts

Proved by: findings/suite/model.test.ts

Written in: findings/src/governance/model.ts

Tests: passed: suite/model.test.ts the severities run from the worst, and a weakness is read from a number or a text and none

FR-002checkpassing

The evidence of a finding MUST be at most 500 characters and MUST have what looks like a credential replaced: the value of an authorization, cookie, API key, password, secret or token header or assignment, a private key, a token of a known shape and any long run of token characters.

Enforced (check): .github: cd commons/findings && bun run verify — suite/model.test.ts

Proved by: findings/suite/model.test.ts

Written in: findings/src/governance/model.ts

Tests: passed: suite/model.test.ts evidence is cut short and what looks like a credential is replaced

FR-003checkpassing

The identity of a finding MUST be the first 16 hexadecimal digits of the SHA-256 of the tool, the rule, the asset (lower case) and the place without its query and fragment, so that the same finding in a later report has the same identity; two findings of one identity in one reading MUST be one, the first kept and the repeats counted.

Enforced (check): .github: cd commons/findings && bun run verify — suite/model.test.ts

Proved by: findings/suite/model.test.ts

Written in: findings/src/governance/model.ts

Tests: passed: suite/model.test.ts the identity of a finding survives a change of query string, differs by rule, asset, place

Acceptance scenarios

  1. Given the same alert found at the same URL with another query string, When the identities are made, Then they are equal, per FR-003.
  2. Given evidence with a bearer token, When it is redacted, Then the token is gone, per FR-002.

Out of scope

Edge cases

  • A weakness identifier of 0 or -1, which tools write for none, is no weakness, per FR-001.

Assumptions

  • A report holds what the tool saw, and the tool saw secrets.

Open questions

  • None.

Key entities

  • Finding, Fingerprint.

Success criteria

SC-001success criterion

The tests of the library pass.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Titles, headings, exports, tables, columns and requirements. Esc closes.