mcp-systemd-crunchtools 0.1.0__tar.gz

mcp_systemd_crunchtools-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src tests
+
+      - name: Run type checker
+        run: uv run mypy src
+
+      - name: Run tests
+        run: uv run pytest -v
+
+  gourmand:
+    name: Code Quality (Gourmand)
+    uses: crunchtools/gatehouse/.github/workflows/gourmand.yml@v0.5.0
+
+  build-container:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build container image
+        run: |
+          docker build -f Containerfile -t mcp-systemd:test .
+
+      - name: Verify container
+        run: |
+          timeout 5 docker run --rm mcp-systemd:test || true
+
+  validate-constitution:
+    name: Constitution Validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/checkout@v4
+        with:
+          repository: crunchtools/constitution
+          path: .constitution
+
+      - name: Validate constitution
+        run: python3 .constitution/validate-constitution.py .specify/memory/constitution.md --verbose

mcp_systemd_crunchtools-0.1.0/.github/workflows/container.yml

@@ -0,0 +1,111 @@
+name: Container Build & Push
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  QUAY_IMAGE: quay.io/crunchtools/mcp-systemd
+  GHCR_IMAGE: ghcr.io/crunchtools/mcp-systemd
+
+jobs:
+  build-and-push-quay:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Quay.io
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: quay.io
+          username: ${{ secrets.QUAY_USERNAME }}
+          password: ${{ secrets.QUAY_PASSWORD }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.QUAY_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Containerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run Trivy vulnerability scanner
+        continue-on-error: true
+        if: github.event_name != 'pull_request'
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: ${{ env.QUAY_IMAGE }}:latest
+          format: "table"
+          exit-code: "0"
+          severity: "CRITICAL,HIGH"
+
+  build-and-push-ghcr:
+    runs-on: ubuntu-latest
+    needs: build-and-push-quay
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ github.token }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.GHCR_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Containerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha

mcp_systemd_crunchtools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_systemd_crunchtools-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,109 @@
+name: Security Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  security-events: write
+
+jobs:
+  dependency-audit:
+    name: Dependency CVE Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install pip-audit
+        run: uv pip install pip-audit
+
+      - name: Run pip-audit
+        id: audit
+        continue-on-error: true
+        run: |
+          uv run pip-audit --format=json --output=audit-results.json || true
+          uv run pip-audit --format=markdown --output=audit-results.md || true
+          if [ -f audit-results.json ]; then
+            VULN_COUNT=$(cat audit-results.json | python -c "import sys,json; data=json.load(sys.stdin); print(len([d for d in data if d.get('vulns', [])]))" 2>/dev/null || echo "0")
+            echo "vuln_count=$VULN_COUNT" >> $GITHUB_OUTPUT
+          else
+            echo "vuln_count=0" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Upload audit results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-audit-results
+          path: |
+            audit-results.json
+            audit-results.md
+          retention-days: 30
+
+      - name: Fail on vulnerabilities (PRs only)
+        if: steps.audit.outputs.vuln_count != '0' && github.event_name == 'pull_request'
+        run: |
+          echo "::error::Security vulnerabilities found in dependencies."
+          exit 1
+
+  container-scan:
+    name: Container Security Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build container image
+        run: docker build -f Containerfile -t mcp-systemd:scan .
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: "mcp-systemd:scan"
+          format: "sarif"
+          output: "trivy-results.sarif"
+          severity: "CRITICAL,HIGH"
+
+      - name: Upload Trivy scan results
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: "trivy-results.sarif"
+
+  codeql:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          queries: security-extended
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:python"

mcp_systemd_crunchtools-0.1.0/.gitignore

@@ -0,0 +1,96 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# uv
+.uv/
+uv.lock
+
+# Local development
+.envrc
+.direnv/
+
+# Gourmand
+.gourmand-cache/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# MCP Registry auth tokens
+.mcpregistry_*

mcp_systemd_crunchtools-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+        stages: [pre-commit, pre-merge-commit]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+        stages: [pre-commit, pre-merge-commit]
+  - repo: https://github.com/crunchtools/constitution
+    rev: v1.0.0
+    hooks:
+      - id: validate-constitution
+
+  # Gourmand runs from its container: the PyPI package of the same name
+  # shadows the real binary on PATH, so a bare `gourmand` is the wrong tool.
+  - repo: local
+    hooks:
+      - id: gourmand
+        name: Gourmand (AI slop detection)
+        entry: podman run --rm -v .:/src:Z -w /src quay.io/crunchtools/gourmand:latest --full
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit, pre-merge-commit]

mcp_systemd_crunchtools-0.1.0/.specify/memory/constitution.md

@@ -0,0 +1,196 @@
+# mcp-systemd-crunchtools Constitution
+
+> **Version:** 0.1.0
+> **Ratified:** 2026-09-19
+> **Status:** Active
+> **Inherits:** [crunchtools/constitution](https://github.com/crunchtools/constitution) v1.0.0
+> **Profile:** MCP Server
+
+This constitution establishes the core principles, constraints, and workflows that govern all development on mcp-systemd-crunchtools.
+
+---
+
+## I. Core Principles
+
+### 1. Five-Layer Security Model
+
+Every change MUST preserve all five security layers. No exceptions.
+
+**Layer 1 — Credential Protection:**
+- This server uses D-Bus system bus socket file permissions for authentication — no API tokens
+- Socket path loaded from `DBUS_SYSTEM_BUS_SOCKET` (default `/run/dbus/system_bus_socket`)
+- There are no Pydantic `SecretStr` fields today because the server holds no secret. If a
+  credential is ever introduced (a remote bus, an auth proxy), it MUST be typed `SecretStr`,
+  MUST come from the environment, and MUST never be logged or returned in a tool response
+
+**Layer 2 — Input Validation:**
+- Unit names validated against `UNIT_NAME_PATTERN` before every D-Bus call and every filesystem path resolution — no paths, no traversal
+- Pydantic models enforce strict data types with `extra="forbid"` for compound write inputs
+- Field length limits on all user-provided strings
+
+**Layer 3 — Protected-Unit Denylist:**
+- `stop`, `restart`, `disable`, `mask`, and `unit_file_remove` refuse to act on a hardcoded set of core system units (dbus, sshd, networking, logind, journald)
+- Extendable via `SYSTEMD_EXTRA_PROTECTED_UNITS`, never shrinkable at runtime
+
+**Layer 4 — Backup Before Mutate:**
+- `unit_file_write` and `unit_file_remove` always copy the file they are about to overwrite or delete to a timestamped backup alongside it before touching it
+
+**Layer 5 — Supply Chain Security:**
+- Weekly automated CVE scanning via GitHub Actions
+- Hummingbird container base images (minimal CVE surface)
+- Gourmand AI slop detection gating all PRs
+
+### 2. Two-Layer Tool Architecture
+
+Tools follow a strict two-layer pattern:
+- `server.py` — `@mcp.tool()` decorated functions that validate args and delegate
+- `tools/*.py` — thin async pass-through functions grouped by domain, calling `dbus_client.py`
+- `dbus_client.py` — all D-Bus wire logic plus journalctl subprocess calls and unit-file disk I/O
+
+Never put business logic in `server.py`. Never put MCP registration in `tools/*.py`.
+
+### 3. Scope: Any Unit, Not Just Podman
+
+Unlike the `service_*` tools this server superseded in mcp-podman-crunchtools (RT #1465), mcp-systemd-crunchtools operates on **any** systemd unit. The protected-unit denylist is what keeps that scope safe, not a Podman-only `ExecStart` filter.
+
+### 4. Three Distribution Channels
+
+Every release MUST be available through all three channels simultaneously:
+
+| Channel | Command | Use Case |
+|---------|---------|----------|
+| uvx | `uvx mcp-systemd-crunchtools` | Zero-install, Claude Code |
+| pip | `pip install mcp-systemd-crunchtools` | Virtual environments |
+| Container | `podman run quay.io/crunchtools/mcp-systemd` | Isolated, systemd |
+
+### 5. Three Transport Modes
+
+The server MUST support all three MCP transports:
+- **stdio** (default) — spawned per-session by Claude Code
+- **SSE** — legacy HTTP transport
+- **streamable-http** — production HTTP, systemd-managed containers
+
+### 6. Semantic Versioning
+
+Follow [Semantic Versioning 2.0.0](https://semver.org/) strictly.
+
+**MAJOR** (breaking changes): Removed/renamed tools, changed parameters
+**MINOR** (new functionality): New tools, new optional parameters
+**PATCH** (fixes): Bug fixes, security patches, test improvements
+
+### 7. AI Code Quality
+
+All code MUST pass Gourmand checks before merge. Zero violations required.
+
+---
+
+## II. Technology Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Language | Python | 3.10+ |
+| MCP Framework | FastMCP | Latest |
+| D-Bus Client | dbus-fast | Latest |
+| Validation | Pydantic | v2 |
+| Container Base | Hummingbird | Latest |
+| Package Manager | uv | Latest |
+| Build System | hatchling | Latest |
+| Linter | ruff | Latest |
+| Type Checker | mypy (strict) | Latest |
+| Tests | pytest + pytest-asyncio | Latest |
+| Slop Detector | gourmand | Latest |
+
+---
+
+## III. Testing Standards
+
+### Mocked D-Bus Tests (MANDATORY)
+
+Every tool MUST have a corresponding mocked test. Tests patch `dbus_client._get_bus` and `dbus_client._call`/`_get_property` — no live D-Bus connection, no host socket required in CI.
+
+**Tool count assertion:** `test_tool_count` MUST be updated whenever tools are added or removed.
+
+### Input Validation Tests
+
+Unit-name validation and `UnitFileWriteInput` MUST have tests in `test_validation.py`:
+- Valid minimal input
+- Invalid/rejected inputs (path traversal, bad suffix, empty strings, extra fields)
+
+---
+
+## IV. Gourmand (AI Slop Detection)
+
+All code MUST pass `gourmand --full .` with **zero violations** before merge.
+
+### Exception Policy
+
+Exceptions MUST have documented justifications in `gourmand-exceptions.toml`. Acceptable reasons:
+- Standard API patterns (assigned port numbers)
+- Framework requirements (CLAUDE.md for Claude Code)
+
+---
+
+## V. Code Quality Gates
+
+Every code change must pass through these gates in order:
+
+1. **Lint** — `uv run ruff check src tests`
+2. **Type Check** — `uv run mypy src`
+3. **Tests** — `uv run pytest -v` (all passing, mocked D-Bus)
+4. **Gourmand** — `gourmand --full .` (zero violations)
+5. **Container Build** — `podman build -f Containerfile .`
+
+---
+
+## VI. Naming Conventions
+
+| Context | Name |
+|---------|------|
+| GitHub repo | `crunchtools/mcp-systemd` |
+| PyPI package | `mcp-systemd-crunchtools` |
+| CLI command | `mcp-systemd-crunchtools` |
+| Python module | `mcp_systemd_crunchtools` |
+| Container image | `quay.io/crunchtools/mcp-systemd` |
+| systemd service | `mcp-systemd.service` |
+| HTTP port | 8022 |
+| License | AGPL-3.0-or-later |
+
+---
+
+## VII. Development Workflow
+
+### Adding a New Tool
+
+1. Add the async function to `dbus_client.py`
+2. Add a thin wrapper to the appropriate `tools/*.py` file and export it from `tools/__init__.py`
+3. Import it in `server.py` and register with `@mcp.tool()`
+4. Add a mocked test in `tests/test_tools.py`
+5. Update the tool count in `test_tool_count`
+6. Run all five quality gates
+7. Update CLAUDE.md and README.md tool listings
+
+---
+
+## VIII. SELinux and Container Deployment
+
+When running in a container with the host D-Bus socket and/or unit directory mounted:
+- Use `--security-opt label=type:container_runtime_t` on the container
+- Mount both paths with `:z`/`:Z` relabel flags
+- The container runs as `container_runtime_t` domain, which can `connectto` the D-Bus socket
+
+---
+
+## IX. Governance
+
+### Amendment Process
+
+1. Create a PR with proposed changes to this constitution
+2. Document rationale in PR description
+3. Require maintainer approval
+4. Update version number upon merge
+
+### Ratification History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 0.1.0 | 2026-09-19 | Initial constitution — split from mcp-podman-crunchtools per RT #1465 |

mcp_systemd_crunchtools-0.1.0/CLAUDE.md

@@ -0,0 +1,68 @@
+# mcp-systemd-crunchtools
+
+MCP server for systemd unit management via D-Bus (system bus), plus journalctl for filtered log queries (no D-Bus equivalent exists for arbitrary journal filters).
+
+## Quick Start
+
+```bash
+uv sync --all-extras
+uv run pytest -v
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DBUS_SYSTEM_BUS_SOCKET` | No | `/run/dbus/system_bus_socket` | D-Bus system bus socket path |
+| `SYSTEMD_UNIT_DIR` | No | `/etc/systemd/system` | Directory unit_file_write/remove operate on |
+| `SYSTEMD_EXTRA_PROTECTED_UNITS` | No | — | Comma-separated units added to the built-in denylist |
+
+## Tools (21)
+
+### Units (3)
+unit_list, unit_status, unit_show
+
+### Lifecycle (9)
+unit_start, unit_stop, unit_restart, unit_reload, unit_enable, unit_disable, unit_mask, unit_unmask, daemon_reload
+
+### Unit files (2) — highest blast radius, writes/deletes host files
+unit_file_write, unit_file_remove
+
+### Troubleshooting (3)
+journal_query, failed_units, list_jobs
+
+### Timers (1)
+timer_list
+
+### System (2)
+system_status, hostinfo
+
+### Sessions (1)
+session_list
+
+## Development Commands
+
+```bash
+uv run ruff check src tests       # Lint
+uv run mypy src                    # Type check
+uv run pytest -v                   # Tests
+gourmand --full .                  # AI slop detection
+podman build -f Containerfile .    # Container build
+```
+
+## Architecture
+
+Two-layer tool pattern:
+- `server.py` — `@mcp.tool()` wrappers with `_tool` suffix
+- `tools/*.py` — thin pass-through async functions grouped by domain, calling `dbus_client.py`
+- `dbus_client.py` — all D-Bus wire logic (systemd1 Manager/Unit/Service/Timer, hostname1, login1) plus the journalctl subprocess call and unit-file disk I/O
+
+## Safety model
+
+This server supersedes mcp-podman's old `service_*` tools and operates on **any** systemd unit, not just Podman-managed ones — split out per RT #1465. Three layers keep that broad scope from being a foot-gun:
+
+1. **Unit name validation** (`models.UNIT_NAME_PATTERN`) — bare names only, no paths, no traversal. Rejects anything that isn't `name.suffix` with a recognized systemd unit suffix.
+2. **Protected-unit denylist** (`config.DEFAULT_PROTECTED_UNITS`, extendable via `SYSTEMD_EXTRA_PROTECTED_UNITS`) — blocks `stop`/`restart`/`disable`/`mask`/`unit_file_remove` on core units (dbus, sshd, networking, logind, journald) so an agent can't take down the box it's running on. Never bypassable for the built-in set.
+3. **Backup-before-write** — `unit_file_write` and `unit_file_remove` always copy the existing file to `<name>.bak-<timestamp>` alongside the original before overwriting or deleting it.
+
+`unit_file_write`/`unit_file_remove` require the host's `SYSTEMD_UNIT_DIR` bind-mounted into the container; every other tool only needs the D-Bus socket.