VNX-1117: Callable with Insufficient Behavioral Summary

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

Overview

VNX-1117 maps to CWE-1117: Callable with Insufficient Behavioral Summary. It reports two concrete shapes in Python:

• a docstring that exists but says nothing: empty (""""""), or only a placeholder such as TODO, ..., Docstring or Description, on one line or split over three;
• a public (name not starting with _) top-level function or class method whose body is 50 or more lines of code and that has no docstring at all.

An undocumented short or private helper is not reported: on its own that is not a weakness, and reporting every function would bury the findings that matter.

Why This Matters

A long public callable with no stated contract cannot be reviewed against one. Reviewers and callers have to infer from the body what inputs it trusts, what it changes and what it returns, and security-relevant assumptions (this argument is already validated, this call must hold a lock) stay implicit. A placeholder docstring is worse than none, because tooling counts the function as documented.

What Gets Flagged

# FLAGGED: placeholder docstring
def hash_password(raw):
    """TODO"""
    return hashlib.sha256(raw.encode()).hexdigest()

# FLAGGED: 50+ line public function, no docstring
def reconcile_ledger(record, options=None):
    step_1 = compute(record, 1)
    ...

# NOT FLAGGED: short helper, private helper, real docstring
def short_helper(x):
    return x * 2

def place_order(cart, user):
    """Submit the cart for the user and return the order id."""
    return cart.submit(user)

Remediation

1. Write a one-line summary of what the function does, followed by its arguments, return value and the exceptions it raises.
2. Replace placeholder docstrings with real ones, or delete them so documentation coverage tools report the gap honestly.
3. Split very long functions so each piece has a contract that fits in a summary.

References

• CWE-1117: Callable with Insufficient Behavioral Summary
• PEP 257: Docstring Conventions

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

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