# VNX-1117: Callable with Insufficient Behavioral Summary

Reports Python functions whose docstring is empty or a placeholder ("""""", """TODO""", """...""", a _summary_ stub or a bare TODO note).

| Field | Value |
|---|---|
| Rule ID | `VNX-1117` |
| Severity | Low |
| SARIF level | `note` |
| Kind | `sast` |
| Languages | Python |
| CWE | [CWE-1117](https://cwe.mitre.org/data/definitions/1117.html) |
| CAPEC | [CAPEC-66](https://capec.mitre.org/data/definitions/66.html) |
| ATT&CK | [T1190](https://attack.mitre.org/techniques/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`](https://github.com/Vulnesis/cli/blob/main/internal/sast/rules/vnx-1117.rego) |

## Overview

VNX-1117 maps to [CWE-1117: Callable with Insufficient Behavioral Summary](https://cwe.mitre.org/data/definitions/1117.html). 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

```python
# 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)
    ...
```

```python
# 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](https://cwe.mitre.org/data/definitions/1117.html)
- [PEP 257: Docstring Conventions](https://peps.python.org/pep-0257/)

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

```text
# nosec vnx-1117
// nosec vnx-1117
```

Or record an ignore rule: `vulnetix ignore add --rule vnx-1117 --reason "..."`. See [Suppressing findings](/sast/guides/suppressing-findings.md).
