privmap 1.0.0__tar.gz

privmap-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

privmap-1.0.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: privmap
+Version: 1.0.0
+Summary: Linux privilege graph engine — model effective access, trace escalation paths.
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=3.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# privmap
+![tests](https://github.com/isaacc2/privmap/workflows/tests/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Linux privilege graph engine. privmap models effective access on a Linux system as a directed graph and traces concrete privilege escalation paths through it.
+
+```
+[CRITICAL] 2 escalation paths found for user: www-data
+
+Path 1 — www-data → root (4 hops)
+  www-data
+    MEMBER_OF  group: adm
+    CAN_WRITE  file: /etc/logrotate.d/nginx  (mode: 0664)
+    EXECUTES   cron: /etc/cron.daily  (runs-as: root)
+  → root
+
+  Risk: Writable logrotate config executed by root daily cron
+  Remediation: chmod 644 /etc/logrotate.d/nginx; chown root:root /etc/logrotate.d/nginx
+```
+
+## Why
+
+Tools like LinPEAS, LinEnum, and BeRoot enumerate privilege-relevant findings as flat lists of independent observations. They report that a file is world-writable, and separately that the same file is executed by a root cron job, but they do not connect those facts into a single exploitable path. The analyst correlates the findings manually.
+
+privmap treats this as a graph reachability problem. Every finding is a node or edge in a directed property graph. The question is not "what misconfigurations exist" but "given this user, what is reachable from here, and through what sequence of relationships."
+
+## Installation
+
+```bash
+pip install privmap
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/isaacc2/privmap.git
+cd privmap
+pip install -e .
+```
+
+Requires Python 3.8 or later.
+
+## Usage
+
+### Live analysis
+
+```bash
+sudo privmap                              # full scan, all users
+sudo privmap --user www-data --user bob   # specific users
+sudo privmap --min-severity high          # filter by severity
+sudo privmap --output json > report.json  # JSON for SIEM
+sudo privmap --output markdown > report.md
+```
+
+Run as root for complete results. Without root, privmap cannot read `/etc/shadow`, walk all of `/etc`, or enumerate other users' processes, and findings will be incomplete.
+
+### Snapshot mode
+
+For offline or forensic analysis, run the collector on the target:
+
+```bash
+sudo ./collect.sh
+```
+
+This produces `privmap_snapshot_<hostname>_<date>.tar.gz`. Transfer the archive to your analysis workstation and run:
+
+```bash
+privmap --snapshot ./privmap_snapshot_target_20250101.tar.gz
+```
+
+The collector is POSIX-compliant and has no runtime dependencies.
+
+### CI/CD integration
+
+```bash
+privmap --exit-code --min-severity critical
+```
+
+Returns non-zero if any path at or above the specified severity is found.
+
+### Other options
+
+```bash
+--scan-paths /etc,/usr,/opt    # custom filesystem scan paths
+--max-depth 8                   # max traversal depth (default 10)
+--export-graph graph.json       # dump full graph as JSON
+-v / -vv                        # verbose / debug logging
+```
+
+## How it works
+
+1. **Ingestion.** Reads system configuration: users, groups, sudo rules, file permissions, cron jobs, systemd units, capabilities, running processes.
+2. **Graph construction.** Each finding becomes a node or edge in a directed property graph.
+3. **Reachability analysis.** DFS traversal from each non-privileged principal toward high-value sinks (root, sudo ALL, dangerous capabilities).
+4. **Semantic filtering.** Eliminates structurally invalid paths, for example a writable file that no privileged process executes.
+5. **Scoring.** Each path is scored on exploitability and impact, then assigned a severity rating.
+6. **Output.** CLI, JSON, or Markdown with per-path remediation.
+
+## Architecture
+
+```
+privmap/
+├── ingestion/
+│   ├── identity.py       # passwd, shadow, group, sudo
+│   ├── filesystem.py     # permission walk, SUID, ACL
+│   ├── processes.py      # /proc, running services
+│   ├── execution.py      # cron, systemd, init.d
+│   └── capabilities.py   # linux capabilities, namespaces
+├── graph/
+│   ├── model.py          # node and edge types
+│   ├── builder.py        # ingestion coordinator
+│   └── traversal.py      # DFS reachability
+├── analysis/
+│   ├── paths.py          # extraction and deduplication
+│   ├── scoring.py        # exploitability and impact
+│   └── remediation.py    # per-path fix suggestions
+├── output/
+│   ├── cli_output.py     # rich terminal renderer
+│   ├── json_export.py
+│   └── markdown_export.py
+└── cli.py                # entry point
+```
+
+## Scope
+
+privmap analyses local Linux privilege relationships. It does not perform network enumeration, run exploits, cover Windows or macOS, or replace a CVE-based vulnerability scanner. It is a structural analysis tool.
+
+## Known limitations
+
+* **Argument-restricted sudo rules** receive a reduced exploitability score but are not fully validated. Rules like `sudo /usr/bin/systemctl restart nginx` may still surface as findings.
+* **Capability binaries from third-party packages** are not on the known-safe allowlist and may produce false positives. The allowlist covers standard system binaries (snap-confine, ping, mtr, chronyd, and similar).
+* **Snapshot mode** falls back to conservative behavior for filesystem permission checks on capability binaries. Live mode is more accurate.
+* **Cron command parsing** uses regex matching on absolute paths, which can match path-like strings inside arguments or comments.
+* **No CVE matching.** privmap does not check binary versions against known vulnerabilities. Use a vulnerability scanner alongside it.
+
+## Use cases
+
+* **System hardening.** Validate least-privilege configurations and catch unintended escalation paths after changes.
+* **Penetration testing.** Replace manual enumeration with deterministic path mapping.
+* **Incident response.** Reconstruct how an attacker may have escalated privileges on a compromised host.
+* **Education and CTF.** Visualise permission chains that are difficult to reason about manually.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+ruff check privmap/
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Run the test suite before submitting a PR. For security vulnerabilities, see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

privmap-1.0.0/README.md

@@ -0,0 +1,157 @@
+# privmap
+![tests](https://github.com/isaacc2/privmap/workflows/tests/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Linux privilege graph engine. privmap models effective access on a Linux system as a directed graph and traces concrete privilege escalation paths through it.
+
+```
+[CRITICAL] 2 escalation paths found for user: www-data
+
+Path 1 — www-data → root (4 hops)
+  www-data
+    MEMBER_OF  group: adm
+    CAN_WRITE  file: /etc/logrotate.d/nginx  (mode: 0664)
+    EXECUTES   cron: /etc/cron.daily  (runs-as: root)
+  → root
+
+  Risk: Writable logrotate config executed by root daily cron
+  Remediation: chmod 644 /etc/logrotate.d/nginx; chown root:root /etc/logrotate.d/nginx
+```
+
+## Why
+
+Tools like LinPEAS, LinEnum, and BeRoot enumerate privilege-relevant findings as flat lists of independent observations. They report that a file is world-writable, and separately that the same file is executed by a root cron job, but they do not connect those facts into a single exploitable path. The analyst correlates the findings manually.
+
+privmap treats this as a graph reachability problem. Every finding is a node or edge in a directed property graph. The question is not "what misconfigurations exist" but "given this user, what is reachable from here, and through what sequence of relationships."
+
+## Installation
+
+```bash
+pip install privmap
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/isaacc2/privmap.git
+cd privmap
+pip install -e .
+```
+
+Requires Python 3.8 or later.
+
+## Usage
+
+### Live analysis
+
+```bash
+sudo privmap                              # full scan, all users
+sudo privmap --user www-data --user bob   # specific users
+sudo privmap --min-severity high          # filter by severity
+sudo privmap --output json > report.json  # JSON for SIEM
+sudo privmap --output markdown > report.md
+```
+
+Run as root for complete results. Without root, privmap cannot read `/etc/shadow`, walk all of `/etc`, or enumerate other users' processes, and findings will be incomplete.
+
+### Snapshot mode
+
+For offline or forensic analysis, run the collector on the target:
+
+```bash
+sudo ./collect.sh
+```
+
+This produces `privmap_snapshot_<hostname>_<date>.tar.gz`. Transfer the archive to your analysis workstation and run:
+
+```bash
+privmap --snapshot ./privmap_snapshot_target_20250101.tar.gz
+```
+
+The collector is POSIX-compliant and has no runtime dependencies.
+
+### CI/CD integration
+
+```bash
+privmap --exit-code --min-severity critical
+```
+
+Returns non-zero if any path at or above the specified severity is found.
+
+### Other options
+
+```bash
+--scan-paths /etc,/usr,/opt    # custom filesystem scan paths
+--max-depth 8                   # max traversal depth (default 10)
+--export-graph graph.json       # dump full graph as JSON
+-v / -vv                        # verbose / debug logging
+```
+
+## How it works
+
+1. **Ingestion.** Reads system configuration: users, groups, sudo rules, file permissions, cron jobs, systemd units, capabilities, running processes.
+2. **Graph construction.** Each finding becomes a node or edge in a directed property graph.
+3. **Reachability analysis.** DFS traversal from each non-privileged principal toward high-value sinks (root, sudo ALL, dangerous capabilities).
+4. **Semantic filtering.** Eliminates structurally invalid paths, for example a writable file that no privileged process executes.
+5. **Scoring.** Each path is scored on exploitability and impact, then assigned a severity rating.
+6. **Output.** CLI, JSON, or Markdown with per-path remediation.
+
+## Architecture
+
+```
+privmap/
+├── ingestion/
+│   ├── identity.py       # passwd, shadow, group, sudo
+│   ├── filesystem.py     # permission walk, SUID, ACL
+│   ├── processes.py      # /proc, running services
+│   ├── execution.py      # cron, systemd, init.d
+│   └── capabilities.py   # linux capabilities, namespaces
+├── graph/
+│   ├── model.py          # node and edge types
+│   ├── builder.py        # ingestion coordinator
+│   └── traversal.py      # DFS reachability
+├── analysis/
+│   ├── paths.py          # extraction and deduplication
+│   ├── scoring.py        # exploitability and impact
+│   └── remediation.py    # per-path fix suggestions
+├── output/
+│   ├── cli_output.py     # rich terminal renderer
+│   ├── json_export.py
+│   └── markdown_export.py
+└── cli.py                # entry point
+```
+
+## Scope
+
+privmap analyses local Linux privilege relationships. It does not perform network enumeration, run exploits, cover Windows or macOS, or replace a CVE-based vulnerability scanner. It is a structural analysis tool.
+
+## Known limitations
+
+* **Argument-restricted sudo rules** receive a reduced exploitability score but are not fully validated. Rules like `sudo /usr/bin/systemctl restart nginx` may still surface as findings.
+* **Capability binaries from third-party packages** are not on the known-safe allowlist and may produce false positives. The allowlist covers standard system binaries (snap-confine, ping, mtr, chronyd, and similar).
+* **Snapshot mode** falls back to conservative behavior for filesystem permission checks on capability binaries. Live mode is more accurate.
+* **Cron command parsing** uses regex matching on absolute paths, which can match path-like strings inside arguments or comments.
+* **No CVE matching.** privmap does not check binary versions against known vulnerabilities. Use a vulnerability scanner alongside it.
+
+## Use cases
+
+* **System hardening.** Validate least-privilege configurations and catch unintended escalation paths after changes.
+* **Penetration testing.** Replace manual enumeration with deterministic path mapping.
+* **Incident response.** Reconstruct how an attacker may have escalated privileges on a compromised host.
+* **Education and CTF.** Visualise permission chains that are difficult to reason about manually.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+ruff check privmap/
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Run the test suite before submitting a PR. For security vulnerabilities, see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

privmap-1.0.0/privmap/__init__.py

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

privmap-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-1.0.0/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"