# VNX-1053: Missing Documentation for Design

Reports Java and Python comments in which the author records that a design or architecture is not documented.

| Field | Value |
|---|---|
| Rule ID | `VNX-1053` |
| Severity | Low |
| SARIF level | `note` |
| Kind | `sast` |
| Languages | Java, Python |
| CWE | [CWE-1053](https://cwe.mitre.org/data/definitions/1053.html) |
| CAPEC | [CAPEC-66](https://capec.mitre.org/data/definitions/66.html) |
| ATT&CK | [T1190](https://attack.mitre.org/techniques/T1190/) |
| CWSS vector | `CWSS:1.0/TI:L/AP:RU/AL:S/IC:N/FC:LT/RP:RU/RL:S/AV:L/AS:N/IN:A/SC:A/BI:L/DI:H/EX:L/EC:N/P:L` |
| Tags | `missing-design-docs` `documentation-debt` `comments` `cwe-1053` |
| Source | [`internal/sast/rules/vnx-1053.rego`](https://github.com/Vulnesis/cli/blob/main/internal/sast/rules/vnx-1053.rego) |

## Overview

VNX-1053 maps to [CWE-1053: Missing Documentation for Design](https://cwe.mitre.org/data/definitions/1053.html). The weakness has no code shape of its own, so the rule reports the one concrete signal source code carries: a Java or Python comment in which the author says the design or architecture is not documented.

- a `TODO`, `FIXME`, `XXX` or `TBD` marker naming the design or architecture together with documenting, explaining or describing it;
- a statement that design documentation is missing or pending (`no design doc yet`, `undocumented design`, `design doc: TBD`).

## Why this matters

Code whose design is not written down is hard to review for security: nobody can check the implementation against assumptions and trust boundaries that exist only in someone's head. A comment admitting this is a reliable marker that the review will be done blind.

Not reported: a TODO about documenting a parameter or function, a TODO to design something (the work, not its documentation), the same words in a string literal, files in other languages, and classes or modules without doc comments (a missing docstring is not evidence that the design is undocumented).

## What gets flagged

```java
// TODO: document the design of the eviction tiers before anyone else touches this
```

```python
# No design doc yet; the settlement ordering is only in Slack.
```

Not flagged:

```python
# TODO: document the timeout parameter
# TODO: design a better retry strategy
```

## Remediation

1. Write the design down where reviewers will find it: an architecture decision record, a design document linked from the code, or a module-level doc comment.
2. Record the assumptions, trust boundaries and failure behaviour, then remove the marker.

## References

- [CWE-1053: Missing Documentation for Design](https://cwe.mitre.org/data/definitions/1053.html)

## Suppressing this rule

Put a `nosec` comment on the line, or on line 1 to cover the whole file. Use the comment marker of the file's language (`#`, `//`, `--` or `;`):

```text
# nosec vnx-1053
// nosec vnx-1053
```

Or record an ignore rule: `vulnetix ignore add --rule vnx-1053 --reason "..."`. See [Suppressing findings](/sast/guides/suppressing-findings.md).
