audit Module (stx.audit)

SciTeX Audit Module

Unified security scanning by orchestrating bandit (Python), shellcheck (shell), pip-audit (deps), and GitHub alerts.

Usage:

from scitex_audit import audit, check_github_alerts

results = audit(“.”) results = audit(“.”, checks=[“python”, “shell”])

# GitHub alerts directly (absorbed from scitex-security per ADR-0001): alerts = check_github_alerts()

scitex.audit.audit(path='.', checks=None, output_file=None)[source]

Run security audit across multiple tools.

Parameters:

  • path (str) – Directory to scan. Defaults to current directory.

  • checks (list[str] | None) – Which checks to run. Options: “python”, “shell”, “deps”, “github”. None means run all available checks.

  • output_file (str | None) – If given, write JSON report to this path.

Returns:

Keys are check names, values have {status, findings, summary}.

Return type:

dict

exception scitex.audit.GitHubSecurityError[source]

Bases: Exception

Raised when GitHub security operations fail.

scitex.audit.check_github_alerts(repo=None, *, auth_check=None, secrets_fn=None, dependabot_fn=None, code_scanning_fn=None)[source]

Check all GitHub security alerts.

Parameters:

  • repo (Optional[str]) – Repository in format ‘owner/repo’. If None, uses current repo.

  • auth_check (Optional[Callable[[], bool]]) – check_gh_auth-shaped callable. Override in tests.

  • secrets_fn (Optional[Callable]) – get_secret_alerts-shaped callable. Override in tests.

  • dependabot_fn (Optional[Callable]) – get_dependabot_alerts-shaped callable. Override in tests.

  • code_scanning_fn (Optional[Callable]) – get_code_scanning_alerts-shaped callable. Override in tests.

Returns:

‘secrets’, ‘dependabot’, ‘code_scanning’

Return type:

Dictionary with keys

Raises:

GitHubSecurityError – If GitHub CLI is not installed or not authenticated

scitex.audit.format_alerts_report(alerts)[source]

Format alerts into a readable text report.

Parameters:

alerts (Dict[str, List[Dict]]) – Dictionary of alerts from check_github_alerts()

Return type:

str

Returns:

Formatted text report

scitex.audit.get_latest_alerts_file(security_dir=None)[source]

Get path to the latest security alerts file.

Parameters:

security_dir (Optional[Path]) – Directory containing security files. Defaults to ~/.scitex/audit/github-alerts/runtime/ (or the project- scope equivalent when inside a git repo, or $SCITEX_AUDIT_DIR).

Return type:

Optional[Path]

Returns:

Path to latest file, or None if not found

scitex.audit.save_alerts_to_file(alerts, output_dir=None, create_symlink=True)[source]

Save alerts to a timestamped file.

Parameters:

  • alerts (Dict[str, List[Dict]]) – Dictionary of alerts from check_github_alerts()

  • output_dir (Optional[Path]) – Directory to save file. Defaults to ~/.scitex/audit/github-alerts/runtime/ (or the project- scope equivalent when inside a git repo, or $SCITEX_AUDIT_DIR).

  • create_symlink (bool) – If True, create ‘security-latest.txt’ symlink

Return type:

Path

Returns:

Path to saved file