How to document excluded source and why it matters

A useful security scan exclusions report names what was left out, why, which security decision it could affect, who accepted the gap, and what will happen next. Record exclusions against a pinned revision and a known inventory. “Skipped tests and generated code” is too vague: a test may show the intended authorization behavior, and generated server code may run in production. The answer changes if the repository inventory itself is incomplete. In that case you do not yet know the full excluded population; report the discovery failure separately and limit every coverage claim. OWASP’s ASVS assessment guidance calls for a defined scope, methods and rationale for exclusions.

The report is for the person deciding whether to trust a result. An AppSec lead can use it to prioritize the next pass; a developer can point out a missing control; a buyer can see where the assessment stops. It is not a way to excuse every omission. The most serious omission may be a shared policy module or deployment setting that changes the meaning of a finding.

Separate five states before calling something excluded

Use one vocabulary for the full chain:

1. Discovered: the path or object appeared in the repository inventory.
2. Acquired: its content was available at the pinned revision.
3. Indexed: a tool stored metadata or search terms so a reviewer could find it.
4. Examined: a named review task actually read the relevant content for a stated question.
5. Question reviewed: a defined behavior was investigated using the content, with counterevidence and a recorded outcome. That outcome may still be inconclusive; “verified file” is not a useful whole-file security state.

The states are not synonyms. An indexed file is not an examined file. A reviewed authorization helper is not proof that every caller invokes it. A requirement may need deployment or runtime evidence that source alone cannot provide. OWASP distinguishes security requirements from how a verifier checks them; the Web Security Testing Guide provides testing methods for a separate kind of evidence.

For each omitted path, record the earliest failed or deliberate step. If a submodule was listed but unavailable, the problem is acquisition, not an “unsupported language.” If a file was acquired and indexed but not read because the time budget expired, call it unexamined. Avoid merging all these into a single “excluded” count; the fix owner and next action differ.

Illustrative ASVS case: an export worker hidden by a default ignore rule

Illustrative example; names, paths, commit and counts are invented. Haven CRM assesses a monorepo at commit 4B8E2. The question is whether a member of customer A can request an export belonging to customer B. The reviewer maps the question to ASVS 5.0.0 authorization requirements: v5.0.0-8.2.2 concerns permission to specific data items, and v5.0.0-8.4.1 concerns cross-tenant controls in a multi-tenant application. Both appear in OWASP’s Authorization chapter.

An initial repository inventory finds apps/api, services/export-worker, libs/authz, deployment files and generated client code. The scan configuration ignores **/generated/** and services/export-worker/**. The worker ignore rule came from an old performance workaround; nobody had checked whether the worker uses the shared authorization library. An alert on the API route cannot be resolved confidently until the worker handoff and its data read are traced. Likewise, a clean API result cannot support the cross-tenant requirement for exports.

The team records the omission before presenting findings:

The business question remains unresolved, not failed or passed, until the missing path is examined and any necessary runtime/deployment evidence is obtained. An unreviewed worker is a coverage gap, not a confirmed vulnerability. If review later finds a source-supported path to another customer’s export, it still needs independent verification before publication as a finding.

Copy this exclusions record

Use one row per meaningful unit. A directory glob may be one row if every file has the same reason and consequence; split it when files play different roles.

Assessment binding: Repository haven-crm, commit 4B8E2, policy source-review-v3, ASVS 5.0.0 Level 2 target for the customer application.

Question and requirement: Can customer A obtain customer B’s export? v5.0.0-8.2.2 and v5.0.0-8.4.1.

Inventory state: Complete for the selected Git tree; submodule and deployment inventory status recorded separately.

Excluded unit: services/export-worker/**, 24 discovered files, 18,420 lines as counted by the inventory method, not acquired or examined. These numbers are illustrative.

Reason: Existing scan ignore glob; not an assessed judgment that the code is irrelevant.

Impact on conclusion: Export authorization cannot be assessed end to end; no pass or “no issue” statement for the worker or cross-tenant export path.

Owner and plan: Platform owner removes the glob and pins the worker artifact; AppSec lead reruns a bounded review of the worker, shared authorization call and data read by 30 October.

Exception decision: None granted. The current assessment is partial for this obligation.

Evidence pointers: Inventory manifest, ignore-policy revision, path list and reviewer decision record; private source stays in the authorized review system.

An exclusion register can be a spreadsheet or text file. It needs stable identifiers, the pinned revision, a link to the scope policy, and a reviewer-readable explanation. Keep source snippets and secrets out of a public summary. A buyer usually needs the affected component, reason and effect on the claim, not a private code dump.

Decide whether an exclusion is acceptable

Ask four questions before accepting one:

Could this unit change the outcome? A shared authorization package, job worker, infrastructure policy or migration often can. If yes, either add it to the current review or keep the related requirement unresolved. A folder name alone is not enough to call it irrelevant.

Is it actually part of the deployed product? Confirm the artifact and configuration with a service owner. Old code may be safe to defer after evidence shows it is not shipped; a path named legacy may still be live. Source inspection alone may not answer deployment mapping.

Can another method cover the control? If source is unavailable but a controlled staging check can test a narrow behavior, record that method and its limits. The alternate method does not make the source examined. Some ASVS requirements involve documentation or environment controls and need evidence outside the repository.

Who owns the residual risk and revisit date? An AppSec lead may document a gap, while a CTO or product owner accepts a release decision within their authority. Do not turn “not in this scan” into silent acceptance. Make a re-entry trigger, such as a release, provider access change or a specific owner supplying the missing artifact.

Re-enter the worker, then split the generated-code exclusion

Continue Haven's synthetic assessment. The selected tree contains 120 discovered files: 24 worker files excluded by the stale glob, 20 generated files grouped as clients, and 76 eligible files. Removing the worker glob makes 100 eligible and 20 excluded. It does not make 24 files reviewed merely because they are now available.

While tracing the acquired worker, the reviewer finds that two of the 20 generated files are server bindings. One selects the export action from the request and invokes the worker admission operation. They are not equivalent to the 18 client artifacts. The owner splits the exclusion row and brings both server files back into scope:

All three versions still total 120 discovered files. The new authorization obligation is “generated server binding preserves trusted action/account context before worker admission.” Its evidence needs the emitted binding, authoritative schema, generator version/configuration and the actual deployed artifact. Reading only the schema would miss a locally modified generated output; reading only output would leave its regeneration path unclear.

The AppSec lead prioritizes this obligation over deep review of the 18 excluded client artifacts because the server binding can alter the export decision. Those 18 stay outside this manual review with the recorded rationale; they are not counted as completed to offset the larger denominator.

The revised customer sentence is: “The assessment scope expanded from 76 to 102 eligible files after reintroducing the worker and identifying two generated server bindings. Review progress is tracked separately; end-to-end export authorization remains incomplete until the new binding obligation and deployment evidence are resolved.” The apparent drop in percentage is improved scope knowledge, not lost work.

Known exclusions remain distinct from undiscovered material. A truncated listing means the total is unknown; it cannot be repaired by adding an exclusion row for files nobody enumerated. Never follow untrusted source symlinks as a shortcut to fill that gap. For generated-code mechanics, use the monorepo guidance after checking its exact artifact roles.

Review exclusion rules when their purpose changes

Haven's stale worker glob began as a performance workaround. That original reason should remain in the history, but it does not justify indefinite omission after the worker becomes central to the assessment question. Ask the rule owner whether the same operational limit still applies and whether a narrower scope or staged acquisition can address it. Removing a broad exclusion need not mean loading every file into every review request.

For the 18 confirmed client artifacts, preserve the evidence that supports their treatment and the trigger for reconsideration. A generator change, a new server-side use, or a changed assessment question can make previously excluded material relevant. The exclusion is a decision for a method and scope, not a permanent declaration that the files have no security significance.

When a rule changes, record the before-and-after populations and the new work created. Do not overwrite S1 with S3 and leave the original report claiming it always included 102 eligible files. The changing denominator tells a useful story: the team learned more about the application boundary and corrected its plan.

The review owner should periodically sample consequential exclusions, starting with those inherited from old defaults or another repository. The purpose is to challenge the rationale, not to force all excluded bytes into the analysis. A small, well-chosen check can reveal that a directory changed roles and prevent a clean result from hiding an entire active service.

Send the service owner the single row with the highest effect on your decision today. Use the monorepo scope measurement guide for a defensible denominator and the ASVS level decision guide when the excluded path changes which requirements matter.