privmap 1.0.0__py3-none-any.whl

privmap/__init__.py

@@ -0,0 +1,2 @@
+"""privmap — Linux privilege graph engine."""
+__version__ = "1.0.0"

privmap/analysis/paths.py

@@ -0,0 +1,49 @@
+"""Path extraction, deduplication, and filtering."""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from privmap.graph.model import EscalationPath, PrivilegeGraph, Severity
+from privmap.graph.traversal import find_escalation_paths
+from privmap.analysis.scoring import score_path
+from privmap.analysis.remediation import generate_remediation
+
+
+def analyze_paths(
+    graph: PrivilegeGraph,
+    source_users: Optional[List[str]] = None,
+    max_depth: int = 10,
+    min_severity: Severity = Severity.INFO,
+) -> List[EscalationPath]:
+    """Full path analysis pipeline: find, score, remediate, filter, sort."""
+    # Find raw paths
+    raw_paths = find_escalation_paths(graph, source_users, max_depth)
+
+    # Score each path
+    for path in raw_paths:
+        score_path(path)
+
+    # Generate remediation advice
+    for path in raw_paths:
+        generate_remediation(path)
+
+    # Filter by minimum severity
+    filtered = [p for p in raw_paths if p.severity and p.severity >= min_severity]
+
+    # Sort: CRITICAL first, then by hop count (shorter = more exploitable)
+    filtered.sort(
+        key=lambda p: (-p.severity.rank if p.severity else 0, p.hop_count)
+    )
+
+    return filtered
+
+
+def group_paths_by_user(
+    paths: List[EscalationPath],
+) -> dict:
+    """Group escalation paths by source user."""
+    groups = {}
+    for path in paths:
+        user = path.source.name
+        groups.setdefault(user, []).append(path)
+    return groups

privmap/analysis/remediation.py

@@ -0,0 +1,148 @@
+"""Generate per-path remediation suggestions."""
+from __future__ import annotations
+
+import os
+from typing import List
+
+from privmap.graph.model import EdgeType, EscalationPath, NodeType
+
+
+def generate_remediation(path: EscalationPath) -> None:
+    """Generate a risk description and remediation for the path. Mutates in place."""
+    steps: List[str] = []
+    risks: List[str] = []
+
+    for i, edge in enumerate(path.edges):
+        source_node = None
+        target_node = None
+        for n in path.nodes:
+            if n.id == edge.source_id:
+                source_node = n
+            if n.id == edge.target_id:
+                target_node = n
+
+        if edge.edge_type == EdgeType.CAN_WRITE and target_node:
+            file_path = target_node.properties.get("path", target_node.name)
+            mode = target_node.properties.get("mode", "")
+            reason = edge.properties.get("reason", "")
+
+            if reason == "world-writable":
+                risks.append(
+                    f"World-writable file {file_path} (mode: {mode})"
+                )
+                steps.append(
+                    f"chmod o-w {file_path}"
+                )
+                owner = target_node.properties.get("owner", "root")
+                steps.append(
+                    f"chown {owner}:root {file_path}"
+                )
+            elif reason == "ACL":
+                risks.append(
+                    f"ACL grants write access to {file_path}"
+                )
+                user_name = source_node.name if source_node else "user"
+                steps.append(
+                    f"setfacl -x u:{user_name} {file_path}"
+                )
+            else:
+                risks.append(
+                    f"Writable file {file_path} (mode: {mode})"
+                )
+                steps.append(
+                    f"chmod 644 {file_path}; chown root:root {file_path}"
+                )
+
+        elif edge.edge_type == EdgeType.GRANTS:
+            cmd = edge.properties.get("command", "")
+            nopasswd = edge.properties.get("nopasswd", False)
+
+            if cmd == "ALL":
+                risks.append(
+                    f"Unrestricted sudo access"
+                    f"{' (NOPASSWD)' if nopasswd else ''}"
+                )
+                if source_node:
+                    steps.append(
+                        f"Restrict sudo rules for {source_node.name} to specific commands"
+                    )
+            elif target_node and target_node.node_type == NodeType.SUDO_RULE:
+                binary = target_node.properties.get("binary", cmd)
+                binary_name = os.path.basename(binary) if "/" in binary else binary
+                risks.append(
+                    f"Sudo rule allows {binary_name}"
+                    f"{' (NOPASSWD)' if nopasswd else ''} — may permit shell escape"
+                )
+                # Suggest sudoedit for editors
+                if binary_name in ("vim", "vi", "nano", "emacs"):
+                    steps.append(
+                        f"Replace sudo {binary_name} rule with sudoedit"
+                    )
+                else:
+                    steps.append(
+                        f"Remove or restrict sudo rule for {binary_name}"
+                    )
+
+        elif edge.edge_type == EdgeType.SUID_EXEC:
+            if target_node:
+                binary = target_node.properties.get("binary", target_node.name)
+                path_str = target_node.properties.get("path", target_node.name)
+                risks.append(
+                    f"SUID binary {binary} ({path_str}) allows privilege escalation"
+                )
+                steps.append(
+                    f"chmod u-s {path_str}"
+                )
+                steps.append(
+                    f"Consider using capabilities instead: setcap cap_needed+ep {path_str}"
+                )
+
+        elif edge.edge_type == EdgeType.HAS_CAPABILITY:
+            if target_node:
+                cap = target_node.name
+                binary = target_node.properties.get("binary", "")
+                risks.append(
+                    f"Binary {binary} has dangerous capability {cap}"
+                )
+                steps.append(
+                    f"setcap -r {binary}"
+                )
+                steps.append(
+                    f"Review if {cap} is strictly necessary for {os.path.basename(binary)}"
+                )
+
+        elif edge.edge_type == EdgeType.EXECUTES:
+            if source_node and target_node:
+                if source_node.node_type == NodeType.CRON_JOB:
+                    run_as = source_node.properties.get("run_as", "root")
+                    script = target_node.properties.get("path", target_node.name)
+                    risks.append(
+                        f"Cron job runs {script} as {run_as}"
+                    )
+                    steps.append(
+                        f"Ensure {script} is owned by root and not writable by others"
+                    )
+                elif source_node.node_type == NodeType.SYSTEMD_UNIT:
+                    unit = source_node.name
+                    script = target_node.properties.get("path", target_node.name)
+                    risks.append(
+                        f"Systemd unit {unit} executes {script}"
+                    )
+                    steps.append(
+                        f"Ensure {script} is owned by root with mode 755 or stricter"
+                    )
+
+        elif edge.edge_type == EdgeType.MEMBER_OF:
+            if target_node:
+                group = target_node.name
+                if group in ("docker", "lxd", "disk", "adm", "shadow"):
+                    risks.append(
+                        f"Membership in privileged group '{group}'"
+                    )
+                    if source_node:
+                        steps.append(
+                            f"Remove {source_node.name} from group {group} unless required"
+                        )
+
+    path.risk_description = "; ".join(risks) if risks else "Privilege escalation path detected"
+    path.remediation = "; ".join(steps) if steps else "Review and restrict permissions along this path"

privmap/analysis/scoring.py

@@ -0,0 +1,138 @@
+"""Score escalation paths on exploitability and impact."""
+from __future__ import annotations
+
+
+from privmap.graph.model import EdgeType, EscalationPath, NodeType, Severity
+
+# Sudo rules with arguments locked down are harder to exploit than unrestricted
+# ones. We reduce exploitability when the command includes arguments, since the
+# user can't freely choose what to run. This isn't foolproof (some argument
+# patterns are still exploitable) but significantly reduces false-positive
+# CRITICAL ratings on rules like: user ALL=(root) /usr/bin/systemctl restart nginx
+_RESTRICTED_SUDO_PENALTY = 2.0
+
+
+def score_path(path: EscalationPath) -> None:
+    """Score a path and assign severity. Mutates the path in place."""
+    exploitability = _compute_exploitability(path)
+    impact = _compute_impact(path)
+
+    path.exploitability_score = exploitability
+    path.impact_score = impact
+
+    combined = (exploitability * 0.6) + (impact * 0.4)
+
+    if combined >= 8.0:
+        path.severity = Severity.CRITICAL
+    elif combined >= 6.0:
+        path.severity = Severity.HIGH
+    elif combined >= 4.0:
+        path.severity = Severity.MEDIUM
+    elif combined >= 2.0:
+        path.severity = Severity.LOW
+    else:
+        path.severity = Severity.INFO
+
+
+def _compute_exploitability(path: EscalationPath) -> float:
+    """Score 0-10 based on how easy the path is to exploit."""
+    score = 10.0
+
+    # Penalize long chains
+    hops = path.hop_count
+    if hops > 5:
+        score -= 5.0
+    elif hops > 3:
+        score -= 2.5
+    elif hops > 1:
+        score -= 0.5
+
+    # Check for timing dependencies (cron = must wait)
+    has_cron_dependency = False
+    has_sudo_nopasswd = False
+    has_suid = False
+    has_restricted_sudo = False
+
+    for edge in path.edges:
+        if edge.edge_type == EdgeType.EXECUTES:
+            # Check if source is a cron job
+            src_node = None
+            for n in path.nodes:
+                if n.id == edge.source_id:
+                    src_node = n
+                    break
+            if src_node and src_node.node_type == NodeType.CRON_JOB:
+                has_cron_dependency = True
+
+        if edge.edge_type == EdgeType.GRANTS:
+            if edge.properties.get("nopasswd"):
+                has_sudo_nopasswd = True
+
+            # Check for argument-restricted sudo rules. A command like
+            # "/usr/bin/systemctl restart nginx" has args after the binary,
+            # which limits what the user can actually do.
+            cmd = edge.properties.get("command", "")
+            if cmd and cmd != "ALL":
+                parts = cmd.strip().split()
+                if len(parts) > 1:
+                    has_restricted_sudo = True
+
+        if edge.edge_type == EdgeType.SUID_EXEC:
+            has_suid = True
+
+    if has_cron_dependency:
+        score -= 2.0  # Must wait for cron trigger
+
+    if has_sudo_nopasswd:
+        score += 1.0  # No password needed is easier
+
+    if has_suid:
+        score += 0.5  # Direct execution, no waiting
+
+    if has_restricted_sudo:
+        score -= _RESTRICTED_SUDO_PENALTY
+
+    # Direct sudo ALL -> root is trivial
+    if hops <= 2 and any(
+        e.edge_type == EdgeType.GRANTS and
+        e.properties.get("command") == "ALL"
+        for e in path.edges
+    ):
+        score = 10.0
+
+    return max(0.0, min(10.0, score))
+
+
+def _compute_impact(path: EscalationPath) -> float:
+    """Score 0-10 based on what the sink grants."""
+    sink = path.sink
+
+    # Root access = maximum impact
+    if sink.node_type == NodeType.USER and sink.properties.get("uid") == 0:
+        return 10.0
+
+    # Sudo ALL = equivalent to root
+    if sink.node_type == NodeType.SUDO_RULE:
+        cmd = sink.properties.get("command", "")
+        if cmd == "ALL":
+            return 10.0
+        # Argument-restricted sudo command — partial access
+        parts = cmd.strip().split()
+        if len(parts) > 1:
+            return 5.0
+        return 7.0  # Unrestricted single command, possible shell escape
+
+    # Dangerous capability
+    if sink.node_type == NodeType.CAPABILITY:
+        cap = sink.name.lower()
+        if cap in ("cap_sys_admin", "cap_dac_override", "cap_setuid"):
+            return 9.0
+        if cap in ("cap_sys_ptrace", "cap_sys_module", "cap_sys_rawio"):
+            return 8.0
+        return 6.0
+
+    # Lateral movement to another user
+    if sink.node_type == NodeType.USER:
+        return 5.0
+
+    return 3.0

privmap/cli.py

@@ -0,0 +1,195 @@
+"""privmap CLI — entry point and argument parsing."""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+import tarfile
+import tempfile
+from typing import List, Optional
+
+from privmap import __version__
+from privmap.graph.builder import GraphBuilder
+from privmap.graph.model import Severity
+from privmap.analysis.paths import analyze_paths
+from privmap.output.cli_output import render_cli
+from privmap.output.json_export import export_json
+from privmap.output.markdown_export import export_markdown
+
+
+def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="privmap",
+        description="Linux privilege graph engine — trace escalation paths.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"privmap {__version__}"
+    )
+    parser.add_argument(
+        "--snapshot",
+        metavar="PATH",
+        help="Path to a snapshot archive (.tar.gz) for offline analysis.",
+    )
+    parser.add_argument(
+        "--user", "-u",
+        action="append",
+        dest="users",
+        metavar="USERNAME",
+        help="Analyse specific user(s). Can be repeated.",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        choices=["cli", "json", "markdown"],
+        default="cli",
+        help="Output format (default: cli).",
+    )
+    parser.add_argument(
+        "--min-severity",
+        choices=["critical", "high", "medium", "low", "info"],
+        default="low",
+        help="Minimum severity to display (default: low).",
+    )
+    parser.add_argument(
+        "--max-depth",
+        type=int,
+        default=10,
+        help="Maximum traversal depth (default: 10).",
+    )
+    parser.add_argument(
+        "--scan-paths",
+        metavar="PATHS",
+        help="Comma-separated list of paths to scan (default: /etc,/usr,/opt,/tmp,/var).",
+    )
+    parser.add_argument(
+        "--export-graph",
+        metavar="FILE",
+        help="Export full graph as JSON to the specified file.",
+    )
+    parser.add_argument(
+        "--exit-code",
+        action="store_true",
+        help="Return non-zero exit code if paths at or above min-severity are found.",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (-v info, -vv debug).",
+    )
+
+    return parser.parse_args(argv)
+
+
+def setup_logging(verbosity: int) -> None:
+    if verbosity >= 2:
+        level = logging.DEBUG
+    elif verbosity >= 1:
+        level = logging.INFO
+    else:
+        level = logging.WARNING
+
+    logging.basicConfig(
+        level=level,
+        format="[%(levelname)s] %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = parse_args(argv)
+    setup_logging(args.verbose)
+    logger = logging.getLogger("privmap")
+
+    # Determine root path
+    root_path = "/"
+    snapshot_mode = False
+    temp_dir = None
+
+    if args.snapshot:
+        snapshot_mode = True
+        if not os.path.isfile(args.snapshot):
+            print(f"Error: Snapshot file not found: {args.snapshot}", file=sys.stderr)
+            return 1
+
+        # Extract snapshot to temp directory
+        temp_dir = tempfile.mkdtemp(prefix="privmap_snapshot_")
+        logger.info("Extracting snapshot to %s", temp_dir)
+        try:
+            with tarfile.open(args.snapshot, "r:gz") as tar:
+                tar.extractall(temp_dir)
+        except (tarfile.TarError, OSError) as e:
+            print(f"Error extracting snapshot: {e}", file=sys.stderr)
+            return 1
+
+        # Find the snapshot directory inside the extracted archive
+        entries = os.listdir(temp_dir)
+        if len(entries) == 1 and os.path.isdir(os.path.join(temp_dir, entries[0])):
+            root_path = os.path.join(temp_dir, entries[0])
+        else:
+            root_path = temp_dir
+
+    # Parse scan paths
+    scan_paths = None
+    if args.scan_paths:
+        scan_paths = [p.strip() for p in args.scan_paths.split(",")]
+
+    # Severity filter
+    min_severity = Severity(args.min_severity.upper())
+
+    try:
+        # Build graph
+        builder = GraphBuilder(
+            root_path=root_path,
+            scan_paths=scan_paths,
+            snapshot_mode=snapshot_mode,
+        )
+        graph = builder.build()
+
+        # Analyze paths
+        paths = analyze_paths(
+            graph,
+            source_users=args.users,
+            max_depth=args.max_depth,
+            min_severity=min_severity,
+        )
+
+        # Export full graph if requested
+        if args.export_graph:
+            graph_json = json.dumps(graph.to_dict(), indent=2, default=str)
+            with open(args.export_graph, "w") as f:
+                f.write(graph_json)
+            logger.info("Graph exported to %s", args.export_graph)
+
+        # Output
+        if args.output == "json":
+            print(export_json(paths, graph))
+        elif args.output == "markdown":
+            print(export_markdown(paths, graph))
+        else:
+            from rich.console import Console
+            console = Console(stderr=True) if args.exit_code else Console()
+            render_cli(paths, graph, console)
+
+        # Exit code
+        if args.exit_code and paths:
+            return 1
+        return 0
+
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return 130
+    except Exception as e:
+        logger.exception("Unexpected error: %s", e)
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    finally:
+        # Clean up temp directory
+        if temp_dir and os.path.isdir(temp_dir):
+            import shutil
+            shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

privmap/graph/builder.py

@@ -0,0 +1,86 @@
+"""Wires ingestion module output into the privilege graph."""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from privmap.graph.model import PrivilegeGraph
+from privmap.ingestion.identity import IdentityIngester
+from privmap.ingestion.filesystem import FilesystemIngester
+from privmap.ingestion.execution import ExecutionIngester
+from privmap.ingestion.capabilities import CapabilityIngester
+from privmap.ingestion.processes import ProcessIngester
+
+logger = logging.getLogger(__name__)
+
+
+class GraphBuilder:
+    """Coordinates all ingestion modules and builds the unified graph."""
+
+    def __init__(
+        self,
+        root_path: str = "/",
+        scan_paths: Optional[list] = None,
+        snapshot_mode: bool = False,
+    ) -> None:
+        self.root_path = root_path
+        self.scan_paths = scan_paths or ["/etc", "/usr", "/opt", "/tmp", "/var"]
+        self.snapshot_mode = snapshot_mode
+        self.graph = PrivilegeGraph()
+
+    def build(self) -> PrivilegeGraph:
+        logger.info("Starting graph construction (root=%s, snapshot=%s)",
+                     self.root_path, self.snapshot_mode)
+
+        # Phase 1: Identity (users, groups, sudo)
+        logger.info("Phase 1: Ingesting identity data...")
+        identity = IdentityIngester(self.root_path, self.snapshot_mode)
+        identity.ingest(self.graph)
+        logger.info(
+            "  Identity complete: %d nodes, %d edges",
+            self.graph.node_count, self.graph.edge_count,
+        )
+
+        # Phase 2: Filesystem permissions
+        logger.info("Phase 2: Ingesting filesystem permissions...")
+        filesystem = FilesystemIngester(
+            self.root_path, self.scan_paths, self.snapshot_mode
+        )
+        filesystem.ingest(self.graph)
+        logger.info(
+            "  Filesystem complete: %d nodes, %d edges",
+            self.graph.node_count, self.graph.edge_count,
+        )
+
+        # Phase 3: Execution contexts (cron, systemd, init.d)
+        logger.info("Phase 3: Ingesting execution contexts...")
+        execution = ExecutionIngester(self.root_path, self.snapshot_mode)
+        execution.ingest(self.graph)
+        logger.info(
+            "  Execution complete: %d nodes, %d edges",
+            self.graph.node_count, self.graph.edge_count,
+        )
+
+        # Phase 4: Capabilities
+        logger.info("Phase 4: Ingesting capabilities...")
+        caps = CapabilityIngester(self.root_path, self.snapshot_mode)
+        caps.ingest(self.graph)
+        logger.info(
+            "  Capabilities complete: %d nodes, %d edges",
+            self.graph.node_count, self.graph.edge_count,
+        )
+
+        # Phase 5: Running processes (skip in snapshot mode unless /proc captured)
+        logger.info("Phase 5: Ingesting process data...")
+        procs = ProcessIngester(self.root_path, self.snapshot_mode)
+        procs.ingest(self.graph)
+        logger.info(
+            "  Processes complete: %d nodes, %d edges",
+            self.graph.node_count, self.graph.edge_count,
+        )
+
+        logger.info(
+            "Graph construction complete: %d nodes, %d edges",
+            self.graph.node_count, self.graph.edge_count,
+        )
+        return self.graph