Skip to content

VNX-1118: Insufficient Documentation of Error Handling Techniques

Reports a Python function whose docstring documents arguments and returns in sections (Google.

Updated 05 Nov 2026Markdown
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

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.

esc
↑ ↓ move↵ openSearches in your browser. A key like autonomy.max or a code like threshold_required jumps straight to it.