Annotations and Evidence of Validations
💡 Practical note:
Tools such as GitHub, GitLab, Xygeni, SonarQube, Semgrep, or even simple editors such as VSCode allow the use of structured comments, labels and special markings indicating that a security validation has been carried out - or that an exception has been accepted.
These annotations make review more effective, help build traceability and serve as auditable evidence of the practical application of the security guidelines.
📌 Objectives
- Make the application of security validations visible and traceable.
- Facilitate technical reviews and internal audits.
- Reinforce the culture of explicit validation and accountability for technical decisions.
- Support exception processes, review of findings and quality control.
👥 Who should apply it
- Developers: when writing or reviewing sensitive code.
- Technical reviewers: when accepting PRs with a security impact.
- Security / AppSec: when assessing exceptions, justifications and traceability.
⏱️ When to apply it
- During development, in code with security requirements or risk.
- At the time of review of sensitive PRs and pull requests.
- When justifying findings from SAST/SCA tools.
- Whenever an exception is accepted or mitigated by design.
🧱 Good annotation practices
-
Use standardised and searchable markings
- E.g.
@sec:input-validated,@sec:auth-required,@sec:checked,@sec:waived
- E.g.
-
Annotate directly in the code, next to the critical function
- Preferably before blocks of sensitive logic.
-
Associate the annotation with the formal reference (requirement, exception, finding)
- E.g.
@sec:justificado #SEC-EXC-014,@sec:reviewed-CWE79
- E.g.
-
Reuse comments in reviews and reports
- Annotations serve as a source for generating evidence and reports.
-
Do not overuse - only where there is an explicit decision
- Useless comments reduce the signal-to-noise ratio and lose technical value.
✅ How to validate
- Automated verification by script (e.g.
grep @sec:or verification in CI). - Technical review checklist with a mark for the presence of tags.
- Manual confirmation by a reviewer that the annotation is justified.
- Integration with traceability panels (e.g. Xygeni, internal dashboards).
🧾 How to evidence it
- Presence of the annotations in versioned code (per commit or PR).
- Scan logs that reference or extract these markings.
- Release reports indicating annotated blocks and their function.
- Traceability table
@sec:*→ requirement/finding → justification (if an exception).
🔄 Link to other practices
| Theme | Associated file |
|---|---|
| Justification of exceptions | addon/05-excecoes-e-justificacoes.md |
| Code review and validation | addon/08-validacoes-codigo.md |
| Development and team guidelines | addon/01, addon/07 |
| Integrated linters and scanners | addon/02, tools with tagging |
📌 Annotations are a lightweight but powerful means of making validations auditable, traceable and collaborative.
They must be part of the normal technical process and respect conventions well defined by the team or organisation.