# VNX-1068: Inconsistency Between Implementation and Documented Design

Java methods and constructors whose Javadoc names a @param the signature does not declare, or documents @return on a void method or a constructor.

| Field | Value |
|---|---|
| Rule ID | `VNX-1068` |
| Severity | Low |
| SARIF level | `note` |
| Kind | `sast` |
| Languages | Java |
| CWE | [CWE-1068](https://cwe.mitre.org/data/definitions/1068.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 | `javadoc-signature-mismatch` `documentation-drift` `maintainability` `java` `cwe-1068` |
| Source | [`internal/sast/rules/vnx-1068.rego`](https://github.com/Vulnesis/cli/blob/main/internal/sast/rules/vnx-1068.rego) |

## Overview

VNX-1068 maps to [CWE-1068: Inconsistency Between Implementation and Documented Design](https://cwe.mitre.org/data/definitions/1068.html). Java: a method or constructor whose Javadoc contradicts its signature. Reported on the declaration line: a `@param name` tag naming a parameter the declaration does not have (a renamed or removed parameter whose documentation was not updated), and a `@return` tag on a method declared `void` or on a constructor. Only block tags at the start of a Javadoc line count. The declaration is read across line breaks after the Javadoc, past annotations (including ones whose arguments span several lines) and line comments, with generic type arguments and annotations removed before parameters are named. Not reported: type-parameter tags (`@param <T>`), class and record Javadoc (record components are documented with @param), parameters that are declared but not documented, matching documentation, inline mentions such as `{@code @param x}` and the inline `{@return ...}` tag, and `@param` text inside string literals. This is the one statically checkable form of the CWE: whether the behaviour matches the prose is not judged.

## Why this matters

This weakness class (Inconsistency Between Implementation and Documented Design) creates a concrete exploit surface: the rule searches for the concrete source-level patterns most commonly associated with CWE-1068 and surfaces them for review. Each finding should be evaluated in context, the rule catches the pattern, not the context.

## What gets flagged

```java
/**
 * @param source the debited account
 * @param target the credited account
 */
public void move(Account from, Account target) { }   // FLAGGED: no parameter named source

/**
 * @return the previous value
 */
public void put(String key, String value) { }        // FLAGGED: @return on void
```

Also flagged: `@return` in a constructor's Javadoc. Not flagged: `{@return the count}` and `{@code @param foo}` written inline, `@param <T>` type-parameter tags, class and record Javadoc, parameters that are simply undocumented, and matching documentation.

## Remediation

1. Review each flagged line and determine whether the pattern represents a real instance of CWE-1068 or a false positive.
2. Replace the flagged construct with a documented safe alternative appropriate to your language and framework.
3. For confirmed false positives, add a `# vulnetix-ignore: VNX-1068` comment on the line.
4. Ensure equivalent test coverage exists to prevent regression.

## References

- [CWE-1068: Inconsistency Between Implementation and Documented Design](https://cwe.mitre.org/data/definitions/1068.html)
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)

## 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-1068
// nosec vnx-1068
```

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