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
CAPEC	CAPEC-66
ATT&CK	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`

Overview

VNX-1068 maps to CWE-1068: Inconsistency Between Implementation and Documented Design. 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

/**
 * @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

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

References

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 ;):

# nosec vnx-1068
// nosec vnx-1068

Or record an ignore rule: vulnetix ignore add --rule vnx-1068 --reason "...". See Suppressing findings.