VNX-1118: Insufficient Documentation of Error Handling Techniques

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

Overview

VNX-1118 maps to CWE-1118: Insufficient Documentation of Error Handling Techniques. It reports a Python function that:

• has a docstring documenting its interface in sections: Google style (Args:, Returns:), NumPy style (Parameters / Returns underlined), or Sphinx fields (:param x:, :returns:, :rtype:); and
• raises a named exception itself (raise ValueError(...), raise errors.AuthError(...) from exc) that the docstring never mentions, with no Raises section or :raises: field.

It is reported once per function, on the first such raise. A bare raise, raise NotImplementedError and a raise inside a nested function are not reported, nor are functions with no docstring or only a one-line summary: there the project does not document a contract, so a missing Raises section is not an omission from one.

Why This Matters

When a documented contract lists every argument but none of the errors, callers handle only the errors they discover by reading the body or by failing in production. Unhandled exceptions surface as 500 pages with stack traces, abort transactions halfway through, or are caught by an over-broad except that hides a security failure.

What Gets Flagged

def charge(card, amount):
    """Charge a card.

    Args:
        card: The stored card token.
        amount: Amount in cents.
    """
    if amount <= 0:
        raise ValueError("amount must be positive")   # FLAGGED

def charge(card, amount):
    """Charge a card.

    Args:
        card: The stored card token.

    Raises:
        ValueError: if amount is not positive.
    """
    raise ValueError("amount must be positive")       # NOT FLAGGED

Remediation

1. Add a Raises: section (Google), a Raises block (NumPy) or :raises ExcType: fields (Sphinx) naming every exception the function raises on purpose and when.
2. Document exceptions that callers are expected to handle; re-raises of unexpected errors do not need listing.

References

• CWE-1118: Insufficient Documentation of Error Handling Techniques
• Google Python Style Guide: Docstrings

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

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