VNX-1111: Incomplete I/O Documentation

Field	Value
Rule ID	VNX-1111
Severity	Low
SARIF level	note
Kind	sast
Languages	Python
CWE	CWE-1111
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	incomplete-io-docs docstring cwe-1111
Source	internal/sast/rules/vnx-1111.rego

Overview

VNX-1111 maps to CWE-1111: Incomplete I/O Documentation. It reports a Python function whose docstring has a parameter section (Google-style Args:/Parameters: or Sphinx :param name:) that leaves out one or more of the function’s own parameters.

Why This Matters

A documented interface that lists some inputs reads as complete. Callers do not learn that an undocumented parameter exists or what it changes (a mode, a timeout, an access-control flag), and reviewers checking how input is handled miss it.

What Gets Flagged

Reported at the def line, naming the missing parameters:

def fetch_report(session, report_id, timeout):    # FLAGGED: 'timeout' undocumented
    """Download a report.

    Args:
        session: HTTP session to use.
        report_id: Identifier of the report.
    """

def write_blob(path, data, mode="wb"):             # FLAGGED: 'mode' undocumented
    """Write bytes to disk.

    :param path: destination file
    :param data: bytes to write
    """

Multi-line signatures, methods, async def and defaults containing commas are handled.

What Does Not Get Flagged

• Functions with no structured parameter section (an undocumented function is a different question).
• self, cls, *args, **kwargs and parameters whose name starts with _.
• NumPy-style sections with dashed underlines (not parsed).
• Test files.

Remediation

1. Add an entry for every parameter to the docstring’s parameter section.
2. If a parameter is internal, rename it with a leading underscore or make it keyword-only and document it.

References

• CWE-1111: Incomplete I/O Documentation

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-1111
// nosec vnx-1111

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