argus-security 1.0.1__py3-none-any.whl

argus/__init__.py

@@ -0,0 +1,3 @@
+"""Argus Security Scanner SDK."""
+
+__version__ = "1.0.1"

argus/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running argus as a module: python -m argus"""
+
+from argus.cli import main
+
+if __name__ == "__main__":
+    main()

argus/architecture_map.py

@@ -0,0 +1,105 @@
+"""Runtime shim for the architecture-map view-model transformer.
+
+The canonical implementation lives at ``scripts/docsite/architecture.py``
+because the transformer follows the docsite-tooling patterns (see the
+``scripts/docsite/builder.py`` / ``scripts/docsite/parsers.py`` style).
+``scripts/docsite/`` isn't a Python package distributed in the
+``argus-security`` wheel, though, so the runtime consumers (the
+FastAPI ``/architecture`` route and the MCP ``argus://architecture``
+resource) can't import it the normal way.
+
+This shim resolves that by locating the file on disk relative to the
+installed argus package and loading it via ``importlib.util``. In
+editable-install workflows (``pip install -e .``) it just works.
+In a clean wheel install with no source checkout, the load fails
+fast and the caller surfaces an actionable error message rather than
+a confusing ``ModuleNotFoundError`` deep in the stack.
+
+Public surface is the same as the canonical module — anything
+exported there is re-exported here. Update the ``_EXPORTS`` list if
+the canonical surface grows.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Any
+
+
+# Re-export list — keep in sync with scripts/docsite/architecture.py.
+_EXPORTS = (
+    "SCHEMA_VERSION",
+    "Registries",
+    "introspect_registries",
+    "load_inputs",
+    "build_view_model",
+    "build_view_model_from_repo",
+    "COLUMNS",
+)
+
+
+def _find_canonical() -> Path | None:
+    """Locate ``scripts/docsite/architecture.py`` on disk.
+
+    Walks up from this file (the argus package) looking for the
+    docsite scripts directory. Editable installs put the argus
+    package next to the ``scripts/`` directory; wheel installs
+    don't, but those are out of scope for this resolver.
+    """
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "scripts" / "docsite" / "architecture.py"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _load_canonical() -> Any:
+    """Import the canonical module via importlib.util.
+
+    Returns the module object. Raises ``ImportError`` with an
+    actionable message when the file can't be found — typical cause
+    is a wheel install without a repo checkout for the SDK
+    introspection inputs.
+    """
+    cached = sys.modules.get("argus._architecture_canonical")
+    if cached is not None:
+        return cached
+    path = _find_canonical()
+    if path is None:
+        raise ImportError(
+            "Architecture-map transformer not found. Expected "
+            "``scripts/docsite/architecture.py`` next to the argus "
+            "package. Install argus in editable mode "
+            "(``pip install -e .`` from the argus repo root) or "
+            "make the repo checkout available on disk."
+        )
+    spec = importlib.util.spec_from_file_location(
+        "argus._architecture_canonical", path,
+    )
+    if spec is None or spec.loader is None:  # pragma: no cover — defensive
+        raise ImportError(f"Cannot build module spec for {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["argus._architecture_canonical"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily forward attribute lookups to the canonical module.
+
+    PEP 562 module-level ``__getattr__`` keeps the import cheap (the
+    canonical file isn't loaded until something actually asks for an
+    export). Anything not in ``_EXPORTS`` raises ``AttributeError``
+    so typos surface immediately.
+    """
+    if name not in _EXPORTS:
+        raise AttributeError(f"module 'argus.architecture_map' has no attribute {name!r}")
+    module = _load_canonical()
+    return getattr(module, name)
+
+
+def __dir__() -> list[str]:  # pragma: no cover — IDE / repl niceties
+    return list(_EXPORTS)

argus/audit/__init__.py

@@ -0,0 +1,16 @@
+"""Audit module -- structured logging, audit trails, and CI platform detection."""
+
+from .logger import get_logger
+from .manifest import AuditManifest, create_manifest, finalize_manifest
+from .platform import CIPlatform, detect_platform
+from .secrets import mask_secrets
+
+__all__ = [
+    "AuditManifest",
+    "CIPlatform",
+    "create_manifest",
+    "detect_platform",
+    "finalize_manifest",
+    "get_logger",
+    "mask_secrets",
+]

argus/audit/logger.py

@@ -0,0 +1,184 @@
+"""Structured logging with colored console output and JSON log file.
+
+Dual output:
+  - Colored console on stderr (human-friendly)
+  - One-JSON-object-per-line log file (machine-friendly evidence)
+
+All output is run through secret masking before being emitted.
+"""
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .secrets import mask_secrets
+
+
+# ---------------------------------------------------------------------------
+# ANSI color codes (stdlib only, no external deps)
+# ---------------------------------------------------------------------------
+
+class _Colors:
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    CYAN = "\033[36m"
+    GRAY = "\033[90m"
+    BG_RED = "\033[41m"
+    BG_GREEN = "\033[42m"
+    BG_YELLOW = "\033[43m"
+
+
+_LEVEL_COLORS = {
+    logging.DEBUG: _Colors.GRAY,
+    logging.INFO: _Colors.CYAN,
+    logging.WARNING: _Colors.YELLOW,
+    logging.ERROR: _Colors.RED,
+    logging.CRITICAL: _Colors.BG_RED + _Colors.BOLD,
+}
+
+
+# ---------------------------------------------------------------------------
+# Formatters
+# ---------------------------------------------------------------------------
+
+class ColoredConsoleFormatter(logging.Formatter):
+    """Colored formatter for terminal output. Masks secrets."""
+
+    def __init__(self, use_color: bool = True):
+        super().__init__()
+        self._use_color = use_color
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Mask the rendered output, NOT record.msg — see the note in
+        # JsonLogFormatter.format() for why masking the format string
+        # breaks ``%s`` substitution.
+        ts = self.formatTime(record, "%H:%M:%S")
+        name = record.name.replace("argus.", "")
+        msg = mask_secrets(record.getMessage())
+
+        if not self._use_color:
+            return f"{ts} {record.levelname:<8} {name} {msg}"
+
+        color = _LEVEL_COLORS.get(record.levelno, "")
+        levelname = f"{color}{record.levelname:<8}{_Colors.RESET}"
+        ts_colored = f"{_Colors.GRAY}{ts}{_Colors.RESET}"
+        module = f"{_Colors.BLUE}{name}{_Colors.RESET}"
+        return f"{ts_colored} {levelname} {module} {msg}"
+
+
+class JsonLogFormatter(logging.Formatter):
+    """Structured JSON formatter for log files. Masks secrets.
+
+    Writes one JSON object per line (JSONL) for easy parsing.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        # NOTE: do NOT mask ``record.msg`` directly. The msg is a
+        # printf-style format string; if its non-whitespace section
+        # matches a secret-masking pattern (e.g., ``"token: %s"`` matches
+        # ``r"token[=:]\s*[^\s]+"``), masking turns the format string
+        # into a literal with no placeholders, and the subsequent
+        # ``record.getMessage()`` raises TypeError on ``%s`` substitution.
+        # Mask the *rendered* message string below instead.
+        entry: dict = {
+            "timestamp": datetime.fromtimestamp(
+                record.created, tz=timezone.utc
+            ).isoformat(),
+            "level": record.levelname,
+            "module": record.name,
+            "function": record.funcName,
+            "line": record.lineno,
+            # ``getMessage()`` re-renders the format string with
+            # ``record.args`` interpolated back in. If a caller passed
+            # a secret as a printf-style arg
+            # (``logger.info("token: %s", real_token)``), that secret
+            # never touched ``record.msg`` — only ``record.args`` — so
+            # masking ``record.msg`` above wouldn't catch it. We mask
+            # the *rendered* result to cover both paths.
+            "message": mask_secrets(record.getMessage()),
+        }
+        # Include extra fields if present (scanner name, phase, etc.)
+        for key in ("scanner", "phase", "image", "duration_ms"):
+            if hasattr(record, key):
+                entry[key] = getattr(record, key)
+        # Defense-in-depth: walk the assembled entry and re-mask any
+        # string a contributor might add to the ``extra`` set above
+        # without remembering to mask first. ``mask_secrets_in_obj``
+        # is idempotent — already-masked values pass through unchanged.
+        from argus.audit.secrets import mask_secrets_in_obj
+        return json.dumps(mask_secrets_in_obj(entry), default=str)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def get_logger(
+    name: str = "argus",
+    output_dir: str | Path | None = None,
+    verbose: bool = False,
+) -> logging.Logger:
+    """Get a configured argus logger with colored console + JSON file output.
+
+    If *output_dir* is provided, writes structured JSON logs to
+    ``{output_dir}/argus.log`` alongside scan results.
+
+    The logger is created once per *name*; subsequent calls with the same
+    name return the existing logger without adding duplicate handlers.
+    """
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        # Existing loggers should still honor a later verbose request,
+        # especially when shared across command flows.
+        for handler in logger.handlers:
+            if isinstance(handler, logging.StreamHandler):
+                desired_level = logging.DEBUG if verbose else logging.INFO
+                if handler.level != desired_level:
+                    handler.setLevel(desired_level)
+
+        # Add file logging if this call requests it and none exists yet.
+        has_file_handler = any(
+            isinstance(handler, logging.FileHandler)
+            for handler in logger.handlers
+        )
+        if output_dir and not has_file_handler:
+            log_dir = Path(output_dir)
+            log_dir.mkdir(parents=True, exist_ok=True)
+            log_path = log_dir / "argus.log"
+            file_handler = logging.FileHandler(
+                log_path, mode="a", encoding="utf-8"
+            )
+            file_handler.setLevel(logging.DEBUG)
+            file_handler.setFormatter(JsonLogFormatter())
+            logger.addHandler(file_handler)
+
+        return logger
+
+    logger.setLevel(logging.DEBUG)
+
+    # Console handler -- colored, INFO level (DEBUG if verbose)
+    use_color = sys.stderr.isatty()
+    console = logging.StreamHandler(sys.stderr)
+    console.setLevel(logging.DEBUG if verbose else logging.INFO)
+    console.setFormatter(ColoredConsoleFormatter(use_color=use_color))
+    logger.addHandler(console)
+
+    # File handler -- JSON, DEBUG level (captures everything)
+    if output_dir:
+        log_dir = Path(output_dir)
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_path = log_dir / "argus.log"
+        file_handler = logging.FileHandler(
+            log_path, mode="a", encoding="utf-8"
+        )
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(JsonLogFormatter())
+        logger.addHandler(file_handler)
+
+    return logger

argus/audit/manifest.py

@@ -0,0 +1,202 @@
+"""Audit manifest -- the evidence package JSON.
+
+The manifest answers the forensic questions: what was scanned, when,
+how, by whom, with what tools, and what was found.  It is the single
+file an investigator reaches for first.
+"""
+
+import hashlib
+import json
+import platform
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .platform import CIPlatform, detect_platform
+
+
+@dataclass
+class ScanPhase:
+    """Timing data for one phase of the scan."""
+
+    name: str
+    started_at: str
+    completed_at: str = ""
+    duration_ms: int = 0
+    status: str = "success"
+    error: str = ""
+
+
+@dataclass
+class AuditManifest:
+    """Complete audit trail for an argus scan run.
+
+    This is the evidence package.  In a security investigation,
+    this file answers: what was scanned, when, how, by whom,
+    with what tools, and what was found.
+    """
+
+    # Identity
+    argus_version: str = ""
+    scan_id: str = ""
+
+    # Timing
+    started_at: str = ""
+    completed_at: str = ""
+    duration_ms: int = 0
+
+    # Provenance (who / where)
+    platform: dict = field(default_factory=dict)
+    hostname: str = ""
+    python_version: str = ""
+    os_info: str = ""
+
+    # What was scanned
+    scan_targets: list[str] = field(default_factory=list)
+    config_file: str = ""
+    config_hash: str = ""
+
+    # How it was scanned
+    scanners_executed: list[str] = field(default_factory=list)
+    tool_versions: dict[str, str] = field(default_factory=dict)
+    container_images: dict[str, str] = field(default_factory=dict)
+    execution_backend: str = ""
+
+    # What was found (summary counts)
+    findings_summary: dict = field(default_factory=dict)
+    exit_code: int = 0
+
+    # Phases (timing per scanner / step)
+    phases: list[dict] = field(default_factory=list)
+
+    # Artifact inventory
+    artifacts: list[dict] = field(default_factory=list)
+
+    def save(self, output_dir: str | Path) -> Path:
+        """Write the manifest to ``argus-audit.json``.
+
+        Every string in the manifest passes through
+        ``mask_secrets_in_obj`` before serialization — defense-in-depth
+        so a future regression that captures a ``docker_cmd``,
+        environment dict, or credential-shaped argv into a manifest
+        field can't leak. Today the manifest schema doesn't include
+        such fields; the redaction pass is here so it stays that way
+        regardless of contributor vigilance.
+        """
+        from argus.audit.secrets import mask_secrets_in_obj
+
+        dest = Path(output_dir)
+        dest.mkdir(parents=True, exist_ok=True)
+        filepath = dest / "argus-audit.json"
+        filepath.write_text(
+            json.dumps(
+                mask_secrets_in_obj(asdict(self)),
+                indent=2, default=str,
+            ),
+            encoding="utf-8",
+        )
+        return filepath
+
+
+def create_manifest(
+    config_path: str | None = None,
+    scan_targets: list[str] | None = None,
+) -> AuditManifest:
+    """Create a new audit manifest with pre-filled provenance.
+
+    Call this at the start of a scan run, then pass the manifest through
+    ``finalize_manifest`` when the scan completes.
+    """
+    try:
+        from argus import __version__
+    except ImportError:
+        __version__ = "unknown"
+
+    ci = detect_platform()
+    now = datetime.now(timezone.utc).isoformat()
+
+    config_hash = ""
+    if config_path and Path(config_path).exists():
+        content = Path(config_path).read_bytes()
+        config_hash = hashlib.sha256(content).hexdigest()
+
+    return AuditManifest(
+        argus_version=__version__,
+        scan_id=str(uuid.uuid4()),
+        started_at=now,
+        platform=asdict(ci),
+        hostname=platform.node(),
+        python_version=platform.python_version(),
+        os_info=f"{platform.system()} {platform.release()}",
+        scan_targets=scan_targets or [],
+        config_file=config_path or "",
+        config_hash=config_hash,
+    )
+
+
+def finalize_manifest(
+    manifest: AuditManifest,
+    summary: Any = None,
+    exit_code: int = 0,
+    output_dir: str | Path = "./argus-results",
+) -> Path:
+    """Finalize and save the audit manifest after scan completes.
+
+    Fills in: completion time, duration, findings summary, and an
+    inventory of every artifact in *output_dir* (with SHA-256 hashes).
+    """
+    now = datetime.now(timezone.utc)
+    manifest.completed_at = now.isoformat()
+
+    if manifest.started_at:
+        started = datetime.fromisoformat(manifest.started_at)
+        manifest.duration_ms = int((now - started).total_seconds() * 1000)
+
+    manifest.exit_code = exit_code
+
+    # Summarize findings if a ScanSummary is provided
+    if summary and hasattr(summary, "results"):
+        manifest.scanners_executed = [r.scanner for r in summary.results]
+        manifest.findings_summary = {
+            "critical": getattr(summary, "critical_count", 0),
+            "high": getattr(summary, "high_count", 0),
+            "medium": getattr(summary, "medium_count", 0),
+            "low": getattr(summary, "low_count", 0),
+            "total": getattr(summary, "total_count", 0),
+        }
+        # Capture container image digests from scan metadata
+        for result in summary.results:
+            meta = getattr(result, "metadata", {}) or {}
+            if meta.get("image") and meta.get("digest"):
+                manifest.container_images[result.scanner] = {
+                    "image": meta["image"],
+                    "digest": meta["digest"],
+                }
+
+    # Flush all log handlers so argus.log is complete before hashing.
+    # Without this, the log file hash in the manifest won't match the
+    # final file because the logger writes entries after hashing.
+    import logging
+    for handler in logging.getLogger("argus").handlers:
+        handler.flush()
+
+    # Inventory output artifacts (hash each file for integrity).
+    # Exclude argus-audit.json (self-referential) and argus.log
+    # (still being written to by the active logger).
+    _EXCLUDE_FROM_HASH = {"argus-audit.json", "argus.log"}
+
+    dest = Path(output_dir)
+    if dest.exists():
+        manifest.artifacts = [
+            {
+                "path": str(f.relative_to(dest)),
+                "size_bytes": f.stat().st_size,
+                "sha256": hashlib.sha256(f.read_bytes()).hexdigest(),
+            }
+            for f in sorted(dest.rglob("*"))
+            if f.is_file() and f.name not in _EXCLUDE_FROM_HASH
+        ]
+
+    return manifest.save(output_dir)

argus/audit/platform.py

@@ -0,0 +1,108 @@
+"""CI/CD platform detection.
+
+Auto-detects the CI environment (GitHub Actions, GitLab CI, Jenkins,
+or local dev) by inspecting well-known environment variables.
+"""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class CIPlatform:
+    """Detected CI/CD platform metadata."""
+
+    name: str = "local"
+    pipeline_id: str = ""
+    job_id: str = ""
+    job_name: str = ""
+    job_url: str = ""
+    pipeline_url: str = ""
+    commit_sha: str = ""
+    commit_branch: str = ""
+    commit_message: str = ""
+    repository: str = ""
+    actor: str = ""
+    runner: str = ""
+    server_url: str = ""
+    event_name: str = ""
+
+
+def detect_platform() -> CIPlatform:
+    """Auto-detect CI platform from environment variables."""
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        return _detect_github()
+    if os.environ.get("GITLAB_CI") == "true":
+        return _detect_gitlab()
+    if os.environ.get("JENKINS_URL"):
+        return _detect_jenkins()
+    return CIPlatform(
+        name="local",
+        actor=os.environ.get("USER", "unknown"),
+    )
+
+
+def _detect_github() -> CIPlatform:
+    """Extract metadata from GitHub Actions environment."""
+    server = os.environ.get("GITHUB_SERVER_URL", "")
+    repo = os.environ.get("GITHUB_REPOSITORY", "")
+    run_id = os.environ.get("GITHUB_RUN_ID", "")
+    run_url = f"{server}/{repo}/actions/runs/{run_id}" if server and repo else ""
+
+    return CIPlatform(
+        name="github",
+        pipeline_id=run_id,
+        job_id=os.environ.get("GITHUB_JOB", ""),
+        job_name=os.environ.get("GITHUB_JOB", ""),
+        job_url=run_url,
+        pipeline_url=run_url,
+        commit_sha=os.environ.get("GITHUB_SHA", ""),
+        commit_branch=(
+            os.environ.get("GITHUB_HEAD_REF", "")
+            or os.environ.get("GITHUB_REF_NAME", "")
+        ),
+        repository=repo,
+        actor=os.environ.get("GITHUB_ACTOR", ""),
+        runner=os.environ.get("RUNNER_NAME", ""),
+        server_url=server or "https://github.com",
+        event_name=os.environ.get("GITHUB_EVENT_NAME", ""),
+    )
+
+
+def _detect_gitlab() -> CIPlatform:
+    """Extract metadata from GitLab CI environment."""
+    return CIPlatform(
+        name="gitlab",
+        pipeline_id=os.environ.get("CI_PIPELINE_ID", ""),
+        job_id=os.environ.get("CI_JOB_ID", ""),
+        job_name=os.environ.get("CI_JOB_NAME", ""),
+        job_url=os.environ.get("CI_JOB_URL", ""),
+        pipeline_url=os.environ.get("CI_PIPELINE_URL", ""),
+        commit_sha=os.environ.get("CI_COMMIT_SHA", ""),
+        commit_branch=(
+            os.environ.get("CI_COMMIT_BRANCH", "")
+            or os.environ.get("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME", "")
+        ),
+        commit_message=os.environ.get("CI_COMMIT_MESSAGE", ""),
+        repository=os.environ.get("CI_PROJECT_PATH", ""),
+        actor=os.environ.get("GITLAB_USER_LOGIN", ""),
+        runner=os.environ.get("CI_RUNNER_DESCRIPTION", ""),
+        server_url=os.environ.get("CI_SERVER_URL", ""),
+        event_name=os.environ.get("CI_PIPELINE_SOURCE", ""),
+    )
+
+
+def _detect_jenkins() -> CIPlatform:
+    """Extract metadata from Jenkins environment."""
+    return CIPlatform(
+        name="jenkins",
+        pipeline_id=os.environ.get("BUILD_NUMBER", ""),
+        job_id=os.environ.get("BUILD_ID", ""),
+        job_name=os.environ.get("JOB_NAME", ""),
+        job_url=os.environ.get("BUILD_URL", ""),
+        commit_sha=os.environ.get("GIT_COMMIT", ""),
+        commit_branch=os.environ.get("GIT_BRANCH", ""),
+        repository=os.environ.get("JOB_NAME", ""),
+        actor=os.environ.get("BUILD_USER", ""),
+        server_url=os.environ.get("JENKINS_URL", ""),
+    )