# VNX-1111: Incomplete I/O Documentation

A Python function whose structured docstring documents some of its parameters but omits others.

| Field | Value |
|---|---|
| Rule ID | `VNX-1111` |
| Severity | Low |
| SARIF level | `note` |
| Kind | `sast` |
| Languages | Python |
| CWE | [CWE-1111](https://cwe.mitre.org/data/definitions/1111.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 | `incomplete-io-docs` `docstring` `cwe-1111` |
| Source | [`internal/sast/rules/vnx-1111.rego`](https://github.com/Vulnesis/cli/blob/main/internal/sast/rules/vnx-1111.rego) |

## Overview

VNX-1111 maps to [CWE-1111: Incomplete I/O Documentation](https://cwe.mitre.org/data/definitions/1111.html). 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:

```python
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.
    """
```

```python
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](https://cwe.mitre.org/data/definitions/1111.html)

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

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