security Module (stx.security)

GitHub Security Alerts Module

Fetches and processes GitHub security alerts (Dependabot, secret scanning, code scanning) via the gh CLI.

Absorbed from scitex-security 0.1.4 into scitex-audit 0.2.0 per ADR-0001 (scitex-dev #139). The public surface (check_github_alerts, save_alerts_to_file, get_latest_alerts_file, format_alerts_report, GitHubSecurityError) is preserved verbatim so consumers that previously did from scitex_security import … get identical behaviour after a one-symbol-name change to from scitex_audit.github import …. The scitex-security 0.2.0 deprecated re-export shim makes the transition flag-day-free for external PyPI users.

Collaborator injection

Per the SciTeX no-mocks rule (PA-306), the production callables that talk to external collaborators (the subprocess module, and the in-module _run_gh_command/check_gh_auth/get_*_alerts helpers) accept keyword-only overrides defaulting to the real module globals. Tests pass real hand-rolled fakes; production code does not pass anything.

exception scitex.security.GitHubSecurityError[source]

Bases: Exception

Raised when GitHub security operations fail.

scitex.security.check_gh_auth(*, run=None)[source]

Check if GitHub CLI is authenticated.

Parameters:

run (Optional[Callable]) – subprocess.run-shaped callable. Defaults to the real subprocess.run. Override in tests.

Return type:

bool

scitex.security.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.security.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.security.get_code_scanning_alerts(repo=None, *, gh_runner=None)[source]

Get code scanning alerts.

Parameters:

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

  • gh_runner (Optional[Callable[[List[str]], str]]) – _run_gh_command-shaped callable. Defaults to _run_gh_command(). Override in tests.

Return type:

List[Dict]

Returns:

List of code scanning alerts

scitex.security.get_default_alerts_dir()[source]

Return the default alerts directory, creating it if needed.

Runs the pre-v0.2 CWD-relative migration when the legacy ./logs/security directory is detected. The user-scope ~/.scitex/security/ migration is run separately on package import (_migrate_legacy_security_dir).

Return type:

Path

scitex.security.get_dependabot_alerts(repo=None, *, gh_runner=None)[source]

Get Dependabot vulnerability alerts.

Parameters:

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

  • gh_runner (Optional[Callable[[List[str]], str]]) – _run_gh_command-shaped callable. Defaults to _run_gh_command(). Override in tests.

Return type:

List[Dict]

Returns:

List of Dependabot alerts

scitex.security.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.security.get_secret_alerts(repo=None, *, gh_runner=None)[source]

Get secret scanning alerts.

Parameters:

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

  • gh_runner (Optional[Callable[[List[str]], str]]) – _run_gh_command-shaped callable. Defaults to _run_gh_command(). Override in tests.

Return type:

List[Dict]

Returns:

List of secret scanning alerts

scitex.security.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