pynydus.security.gitleaks

Gitleaks CLI connector for secret detection.

Wraps the external gitleaks binary to scan directories for secrets (API keys, tokens, passwords) and build SecretRecord entries with {{SECRET_NNN}} placeholders. Descriptions never contain secret substrings.

Requires gitleaks v8+ on PATH or NYDUS_GITLEAKS_PATH.

Module Contents

Classes

Finding

One row from gitleaks JSON report output.

Functions

find_gitleaks	Resolve the gitleaks executable path.
run_gitleaks_scan	Run gitleaks directory on root and parse JSON findings.
apply_gitleaks_findings	Replace gitleaks matches with placeholders and build secret records.

Data

logger

API

pynydus.security.gitleaks.logger

‘getLogger(…)’

class pynydus.security.gitleaks.Finding

One row from gitleaks JSON report output.

Attributes: file: Absolute path to the file (as reported by gitleaks). rule_id: Rule identifier. match: Matched substring in the file. start_line: 1-based line number. start_column: Start column (1-based, gitleaks convention). end_column: End column. secret: Optional Secret field from JSON. preferred replacement text when it appears verbatim in the file content.

file: str

None

rule_id: str

None

match: str

None

start_line: int

None

start_column: int

None

end_column: int

None

secret: str = <Multiline-String>

pynydus.security.gitleaks.find_gitleaks() → str | None

Resolve the gitleaks executable path.

Returns: Absolute path to the binary, or None if not found.

Note: NYDUS_GITLEAKS_PATH is checked first, then PATH via shutil.which.

pynydus.security.gitleaks.run_gitleaks_scan(root: pathlib.Path) → list[pynydus.security.gitleaks.Finding]

Run gitleaks directory on root and parse JSON findings.

Args: root: Directory tree to scan (v8.18+ gitleaks directory mode).

Returns: Parsed Finding rows. Empty if the report file is empty.

Raises: RuntimeError: If the binary is missing or gitleaks exits with a code other than 0 (success) or 1 (leaks found).

Note: Exit code 1 means leaks were found, not a failed run. Report JSON is written to a temp file because -r - is unreliable on some platforms.

pynydus.security.gitleaks.apply_gitleaks_findings(files: dict[str, str], findings: list[pynydus.security.gitleaks.Finding], *, temp_root: pathlib.Path, start_index: int = 1) → tuple[dict[str, str], list[pynydus.api.schemas.SecretRecord], int]

Replace gitleaks matches with placeholders and build secret records.

Args: files: Original path-to-content map (keys match the tree under temp_root). findings: Parsed gitleaks rows for that tree. temp_root: Temp directory path that was passed to :func:run_gitleaks_scan (used to map absolute paths back to keys). start_index: Starting index for {{SECRET_NNN}} numbering.

Returns: Tuple of (redacted file map, new SecretRecord list, next index) after the last placeholder.