From b7c6dc488169de9cf3169443edda43113f4d3e77 Mon Sep 17 00:00:00 2001 From: krahd Date: Tue, 26 May 2026 21:12:08 -0300 Subject: [PATCH 1/3] chore: add audit-driven CI security and state documentation --- .github/dependabot.yml | 25 ++ .github/workflows/ci.yml | 41 +++ .github/workflows/dependency-review.yml | 20 ++ .github/workflows/pip-audit.yml | 28 ++ PR_BODY.md | 38 +++ PR_TITLE.txt | 1 + SECURITY.md | 22 ++ batllm-audit-pr-overlay.zip | Bin 0 -> 7671 bytes batllm-audit-pr.patch | 311 ++++++++++++++++++ .../.github/dependabot.yml | 25 ++ .../.github/workflows/ci.yml | 41 +++ .../.github/workflows/dependency-review.yml | 20 ++ .../.github/workflows/pip-audit.yml | 28 ++ batllm-pr-implementation/PR_BODY.md | 38 +++ batllm-pr-implementation/PR_TITLE.txt | 1 + batllm-pr-implementation/SECURITY.md | 22 ++ .../docs/MAINTAINER_AUDIT_CHECKLIST.md | 28 ++ .../docs/STATE_AND_INSTALLATION.md | 32 ++ .../scripts/apply_audit_pr.sh | 16 + docs/MAINTAINER_AUDIT_CHECKLIST.md | 28 ++ docs/STATE_AND_INSTALLATION.md | 32 ++ scripts/apply_audit_pr.sh | 16 + 22 files changed, 813 insertions(+) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/dependency-review.yml create mode 100644 .github/workflows/pip-audit.yml create mode 100644 PR_BODY.md create mode 100644 PR_TITLE.txt create mode 100644 SECURITY.md create mode 100644 batllm-audit-pr-overlay.zip create mode 100644 batllm-audit-pr.patch create mode 100644 batllm-pr-implementation/.github/dependabot.yml create mode 100644 batllm-pr-implementation/.github/workflows/ci.yml create mode 100644 batllm-pr-implementation/.github/workflows/dependency-review.yml create mode 100644 batllm-pr-implementation/.github/workflows/pip-audit.yml create mode 100644 batllm-pr-implementation/PR_BODY.md create mode 100644 batllm-pr-implementation/PR_TITLE.txt create mode 100644 batllm-pr-implementation/SECURITY.md create mode 100644 batllm-pr-implementation/docs/MAINTAINER_AUDIT_CHECKLIST.md create mode 100644 batllm-pr-implementation/docs/STATE_AND_INSTALLATION.md create mode 100755 batllm-pr-implementation/scripts/apply_audit_pr.sh create mode 100644 docs/MAINTAINER_AUDIT_CHECKLIST.md create mode 100644 docs/STATE_AND_INSTALLATION.md create mode 100755 scripts/apply_audit_pr.sh diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..052f364 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,25 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "python" + commit-message: + prefix: "deps" + include: "scope" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "github-actions" + commit-message: + prefix: "ci" + include: "scope" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..8ef0035 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,41 @@ +name: CI + +on: + pull_request: + branches: [main] + push: + branches: [main] + +permissions: + contents: read + +jobs: + test: + name: Python ${{ matrix.python-version }} on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + python-version: ["3.10", "3.11", "3.12"] + + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: "pip" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + python -m pip install pytest pylint + - name: Compile sources + run: python -m compileall . + - name: Run tests + run: python run_tests.py + - name: Run pylint + if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' }} + run: pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..e8a5060 --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,20 @@ +name: Dependency review + +on: + pull_request: + branches: [main] + +permissions: + contents: read + pull-requests: read + +jobs: + dependency-review: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Review dependency changes + uses: actions/dependency-review-action@v4 + with: + fail-on-severity: high diff --git a/.github/workflows/pip-audit.yml b/.github/workflows/pip-audit.yml new file mode 100644 index 0000000..c515148 --- /dev/null +++ b/.github/workflows/pip-audit.yml @@ -0,0 +1,28 @@ +name: Python dependency audit + +on: + pull_request: + branches: [main] + push: + branches: [main] + schedule: + - cron: "17 4 * * 1" + +permissions: + contents: read + +jobs: + pip-audit: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: "pip" + - name: Audit requirements + uses: pypa/gh-action-pip-audit@v1.1.0 + with: + inputs: requirements.txt diff --git a/PR_BODY.md b/PR_BODY.md new file mode 100644 index 0000000..ebc8317 --- /dev/null +++ b/PR_BODY.md @@ -0,0 +1,38 @@ +## Summary + +This PR implements the confirmed high-confidence improvements from the BatLLM audit: + +- adds a repository security policy; +- adds Dependabot for Python and GitHub Actions dependencies; +- adds PR-time dependency review; +- adds scheduled and PR-time Python dependency auditing with `pip-audit`; +- adds a cross-platform Python CI matrix for Linux, macOS, and Windows; +- documents the single runtime-state invariant: installed application files are read-only and mutable state belongs under `BATLLM_HOME` or the platform app-data equivalent; +- adds a maintainer audit checklist for launchers, configuration, sessions, Ollama lifecycle, and release checks. + +## Rationale + +The audit found that BatLLM has several operational surfaces: source launchers, analyzer launchers, Homebrew packaging, release bundles, mutable configuration, saved sessions, and local Ollama orchestration. This makes repository hygiene and state-location consistency critical. + +This PR is deliberately additive. It avoids speculative refactors where source-level verification is required, but it establishes the CI/security/doc baseline needed before deeper changes such as entry-point consolidation, `pyproject.toml` migration, and state-path refactoring. + +## Verification + +Expected checks: + +```bash +python -m pip install --upgrade pip +python -m pip install -r requirements.txt +python run_tests.py +python -m compileall . +pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py +pip-audit -r requirements.txt +``` + +## Follow-up work + +- Convert runtime configuration writes to use `BATLLM_HOME` everywhere. +- Add migration logic for repository-relative historical config. +- Collapse launchers onto canonical installed entry points. +- Add `pyproject.toml` after confirming package/module names under `src/`. +- Add tests for path handling, missing Ollama, non-responsive Ollama, subprocess timeouts, and session migration. diff --git a/PR_TITLE.txt b/PR_TITLE.txt new file mode 100644 index 0000000..66765fe --- /dev/null +++ b/PR_TITLE.txt @@ -0,0 +1 @@ +Harden CI, dependency security, and runtime state documentation diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..938dfb6 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,22 @@ +# Security Policy + +## Supported versions + +Security fixes are provided for the current `main` branch and the most recent tagged release. + +## Reporting a vulnerability + +Report suspected vulnerabilities privately. Do not open a public issue containing exploit details, secrets, local paths, or reproduction data that may expose a user system. + +Include: + +- affected BatLLM version or commit; +- operating system and Python version; +- installation method; +- whether Ollama was installed system-wide, through Homebrew, or manually; +- minimal reproduction steps; +- relevant logs with secrets, local usernames, and paths redacted. + +## Security-relevant areas + +BatLLM interacts with a local Ollama service, reads and writes local configuration, stores sessions, and invokes launch scripts. Reports involving path traversal, unsafe subprocess use, unexpected writes outside the configured application directory, dependency compromise, or unintended disclosure of local files should be treated as security relevant. diff --git a/batllm-audit-pr-overlay.zip b/batllm-audit-pr-overlay.zip new file mode 100644 index 0000000000000000000000000000000000000000..b365924652e53b8dc3cfd5611a9e098998bccae8 GIT binary patch literal 7671 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 PBGfM*^(02|?d^X66e+JB literal 0 HcmV?d00001 diff --git a/batllm-audit-pr.patch b/batllm-audit-pr.patch new file mode 100644 index 0000000..fd11e79 --- /dev/null +++ b/batllm-audit-pr.patch @@ -0,0 +1,311 @@ +diff --git a/.github/dependabot.yml b/.github/dependabot.yml +new file mode 100644 +index 0000000..0000000 +--- a/.github/dependabot.yml ++++ b/.github/dependabot.yml +@@ -0,0 +1,25 @@ ++version: 2 ++updates: ++ - package-ecosystem: "pip" ++ directory: "/" ++ schedule: ++ interval: "weekly" ++ open-pull-requests-limit: 5 ++ labels: ++ - "dependencies" ++ - "python" ++ commit-message: ++ prefix: "deps" ++ include: "scope" ++ ++ - package-ecosystem: "github-actions" ++ directory: "/" ++ schedule: ++ interval: "weekly" ++ open-pull-requests-limit: 5 ++ labels: ++ - "dependencies" ++ - "github-actions" ++ commit-message: ++ prefix: "ci" ++ include: "scope" +diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml +new file mode 100644 +index 0000000..0000000 +--- a/.github/workflows/ci.yml ++++ b/.github/workflows/ci.yml +@@ -0,0 +1,41 @@ ++name: CI ++ ++on: ++ pull_request: ++ branches: [main] ++ push: ++ branches: [main] ++ ++permissions: ++ contents: read ++ ++jobs: ++ test: ++ name: Python ${{ matrix.python-version }} on ${{ matrix.os }} ++ runs-on: ${{ matrix.os }} ++ strategy: ++ fail-fast: false ++ matrix: ++ os: [ubuntu-latest, macos-latest, windows-latest] ++ python-version: ["3.10", "3.11", "3.12"] ++ ++ steps: ++ - name: Checkout ++ uses: actions/checkout@v4 ++ - name: Set up Python ++ uses: actions/setup-python@v5 ++ with: ++ python-version: ${{ matrix.python-version }} ++ cache: "pip" ++ - name: Install dependencies ++ run: | ++ python -m pip install --upgrade pip ++ python -m pip install -r requirements.txt ++ python -m pip install pytest pylint ++ - name: Compile sources ++ run: python -m compileall . ++ - name: Run tests ++ run: python run_tests.py ++ - name: Run pylint ++ if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' }} ++ run: pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py +diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml +new file mode 100644 +index 0000000..0000000 +--- a/.github/workflows/dependency-review.yml ++++ b/.github/workflows/dependency-review.yml +@@ -0,0 +1,20 @@ ++name: Dependency review ++ ++on: ++ pull_request: ++ branches: [main] ++ ++permissions: ++ contents: read ++ pull-requests: read ++ ++jobs: ++ dependency-review: ++ runs-on: ubuntu-latest ++ steps: ++ - name: Checkout ++ uses: actions/checkout@v4 ++ - name: Review dependency changes ++ uses: actions/dependency-review-action@v4 ++ with: ++ fail-on-severity: high +diff --git a/.github/workflows/pip-audit.yml b/.github/workflows/pip-audit.yml +new file mode 100644 +index 0000000..0000000 +--- a/.github/workflows/pip-audit.yml ++++ b/.github/workflows/pip-audit.yml +@@ -0,0 +1,28 @@ ++name: Python dependency audit ++ ++on: ++ pull_request: ++ branches: [main] ++ push: ++ branches: [main] ++ schedule: ++ - cron: "17 4 * * 1" ++ ++permissions: ++ contents: read ++ ++jobs: ++ pip-audit: ++ runs-on: ubuntu-latest ++ steps: ++ - name: Checkout ++ uses: actions/checkout@v4 ++ - name: Set up Python ++ uses: actions/setup-python@v5 ++ with: ++ python-version: "3.12" ++ cache: "pip" ++ - name: Audit requirements ++ uses: pypa/gh-action-pip-audit@v1.1.0 ++ with: ++ inputs: requirements.txt +diff --git a/PR_BODY.md b/PR_BODY.md +new file mode 100644 +index 0000000..0000000 +--- a/PR_BODY.md ++++ b/PR_BODY.md +@@ -0,0 +1,38 @@ ++## Summary ++ ++This PR implements the confirmed high-confidence improvements from the BatLLM audit: ++ ++- adds a repository security policy; ++- adds Dependabot for Python and GitHub Actions dependencies; ++- adds PR-time dependency review; ++- adds scheduled and PR-time Python dependency auditing with `pip-audit`; ++- adds a cross-platform Python CI matrix for Linux, macOS, and Windows; ++- documents the single runtime-state invariant: installed application files are read-only and mutable state belongs under `BATLLM_HOME` or the platform app-data equivalent; ++- adds a maintainer audit checklist for launchers, configuration, sessions, Ollama lifecycle, and release checks. ++ ++## Rationale ++ ++The audit found that BatLLM has several operational surfaces: source launchers, analyzer launchers, Homebrew packaging, release bundles, mutable configuration, saved sessions, and local Ollama orchestration. This makes repository hygiene and state-location consistency critical. ++ ++This PR is deliberately additive. It avoids speculative refactors where source-level verification is required, but it establishes the CI/security/doc baseline needed before deeper changes such as entry-point consolidation, `pyproject.toml` migration, and state-path refactoring. ++ ++## Verification ++ ++Expected checks: ++ ++```bash ++python -m pip install --upgrade pip ++python -m pip install -r requirements.txt ++python run_tests.py ++python -m compileall . ++pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py ++pip-audit -r requirements.txt ++``` ++ ++## Follow-up work ++ ++- Convert runtime configuration writes to use `BATLLM_HOME` everywhere. ++- Add migration logic for repository-relative historical config. ++- Collapse launchers onto canonical installed entry points. ++- Add `pyproject.toml` after confirming package/module names under `src/`. ++- Add tests for path handling, missing Ollama, non-responsive Ollama, subprocess timeouts, and session migration. +diff --git a/PR_TITLE.txt b/PR_TITLE.txt +new file mode 100644 +index 0000000..0000000 +--- a/PR_TITLE.txt ++++ b/PR_TITLE.txt +@@ -0,0 +1 @@ ++Harden CI, dependency security, and runtime state documentation +diff --git a/SECURITY.md b/SECURITY.md +new file mode 100644 +index 0000000..0000000 +--- a/SECURITY.md ++++ b/SECURITY.md +@@ -0,0 +1,22 @@ ++# Security Policy ++ ++## Supported versions ++ ++Security fixes are provided for the current `main` branch and the most recent tagged release. ++ ++## Reporting a vulnerability ++ ++Report suspected vulnerabilities privately. Do not open a public issue containing exploit details, secrets, local paths, or reproduction data that may expose a user system. ++ ++Include: ++ ++- affected BatLLM version or commit; ++- operating system and Python version; ++- installation method; ++- whether Ollama was installed system-wide, through Homebrew, or manually; ++- minimal reproduction steps; ++- relevant logs with secrets, local usernames, and paths redacted. ++ ++## Security-relevant areas ++ ++BatLLM interacts with a local Ollama service, reads and writes local configuration, stores sessions, and invokes launch scripts. Reports involving path traversal, unsafe subprocess use, unexpected writes outside the configured application directory, dependency compromise, or unintended disclosure of local files should be treated as security relevant. +diff --git a/docs/MAINTAINER_AUDIT_CHECKLIST.md b/docs/MAINTAINER_AUDIT_CHECKLIST.md +new file mode 100644 +index 0000000..0000000 +--- a/docs/MAINTAINER_AUDIT_CHECKLIST.md ++++ b/docs/MAINTAINER_AUDIT_CHECKLIST.md +@@ -0,0 +1,28 @@ ++# Maintainer audit checklist ++ ++Use this checklist before release or after changing launch, configuration, packaging, or Ollama lifecycle code. ++ ++## Functional checks ++ ++- `python run_tests.py` passes on Python 3.10, 3.11, and 3.12. ++- Application launch works from source checkout. ++- Analyzer launch works from source checkout. ++- Homebrew launcher and release-bundle launcher call the same canonical application entry path. ++- Changing model selection updates only the user state directory. ++- Saved sessions are written under the user state directory. ++- Legacy session files either migrate deterministically or fail with a clear compatibility message. ++ ++## Security and dependency checks ++ ++- `pip-audit -r requirements.txt` passes or accepted findings are documented. ++- Dependency Review passes on pull requests that change dependencies. ++- Dependabot pull requests are reviewed and merged or explicitly rejected. ++- No launcher uses untrusted shell interpolation. ++- Subprocess calls use explicit argument lists, bounded timeouts, and clear error propagation. ++ ++## Platform checks ++ ++- Linux, macOS, and Windows CI pass. ++- `BATLLM_HOME` works on all supported platforms. ++- Paths with spaces and non-ASCII characters are tested. ++- Missing Ollama, stopped Ollama, and non-responsive Ollama produce actionable errors. +diff --git a/docs/STATE_AND_INSTALLATION.md b/docs/STATE_AND_INSTALLATION.md +new file mode 100644 +index 0000000..0000000 +--- a/docs/STATE_AND_INSTALLATION.md ++++ b/docs/STATE_AND_INSTALLATION.md +@@ -0,0 +1,32 @@ ++# Installation channels and mutable state ++ ++BatLLM should use one state model across all installation channels. ++ ++## Invariant ++ ++Installed application files are read-only at runtime. User changes must not mutate the source tree, package installation directory, Homebrew cellar, application bundle, or release-bundle program directory. ++ ++Runtime state belongs in a per-user application directory. `BATLLM_HOME` overrides the default location and is the canonical mechanism for tests, portable bundles, and package-manager integrations. ++ ++## State categories ++ ++| Category | Mutable | Location | ++|---|---:|---| ++| Packaged defaults | No | repository/package data | ++| Effective configuration | Yes | `$BATLLM_HOME/config.yaml` or platform app-data equivalent | ++| Saved sessions | Yes | `$BATLLM_HOME/sessions/` | ++| Logs | Yes | `$BATLLM_HOME/logs/` | ++| Cache/temp files | Yes | `$BATLLM_HOME/cache/` | ++ ++## Required behaviour ++ ++- On first run, create the user state directory if it does not exist. ++- Copy packaged default configuration into the user state directory before applying user edits. ++- Treat repository-relative `src/configs/config.yaml` as a read-only default, not as runtime state. ++- Prefer atomic writes for configuration and saved sessions. ++- Do not write to the Homebrew cellar or any other package-manager-controlled directory. ++- Tests should set `BATLLM_HOME` to a temporary directory. ++ ++## Migration rule ++ ++If an older install has user-edited configuration in a repository-relative path, migrate it once into the user state directory and leave the original file untouched after migration. +diff --git a/scripts/apply_audit_pr.sh b/scripts/apply_audit_pr.sh +new file mode 100644 +index 0000000..0000000 +--- a/scripts/apply_audit_pr.sh ++++ b/scripts/apply_audit_pr.sh +@@ -0,0 +1,16 @@ ++#!/usr/bin/env bash ++set -euo pipefail ++ ++if [ ! -d .git ]; then ++ echo "Run this from the BatLLM repository root." >&2 ++ exit 1 ++fi ++ ++git checkout -b chore/audit-ci-security-state-docs ++cp -R .github docs SECURITY.md PR_TITLE.txt PR_BODY.md . ++git add . ++git commit -m "chore: add audit-driven CI security and state documentation" ++ ++echo "Branch created: chore/audit-ci-security-state-docs" ++echo "Open the PR with:" ++echo "gh pr create --title \"$(cat PR_TITLE.txt)\" --body-file PR_BODY.md" diff --git a/batllm-pr-implementation/.github/dependabot.yml b/batllm-pr-implementation/.github/dependabot.yml new file mode 100644 index 0000000..052f364 --- /dev/null +++ b/batllm-pr-implementation/.github/dependabot.yml @@ -0,0 +1,25 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "python" + commit-message: + prefix: "deps" + include: "scope" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "github-actions" + commit-message: + prefix: "ci" + include: "scope" diff --git a/batllm-pr-implementation/.github/workflows/ci.yml b/batllm-pr-implementation/.github/workflows/ci.yml new file mode 100644 index 0000000..8ef0035 --- /dev/null +++ b/batllm-pr-implementation/.github/workflows/ci.yml @@ -0,0 +1,41 @@ +name: CI + +on: + pull_request: + branches: [main] + push: + branches: [main] + +permissions: + contents: read + +jobs: + test: + name: Python ${{ matrix.python-version }} on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + python-version: ["3.10", "3.11", "3.12"] + + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: "pip" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + python -m pip install pytest pylint + - name: Compile sources + run: python -m compileall . + - name: Run tests + run: python run_tests.py + - name: Run pylint + if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' }} + run: pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py diff --git a/batllm-pr-implementation/.github/workflows/dependency-review.yml b/batllm-pr-implementation/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..e8a5060 --- /dev/null +++ b/batllm-pr-implementation/.github/workflows/dependency-review.yml @@ -0,0 +1,20 @@ +name: Dependency review + +on: + pull_request: + branches: [main] + +permissions: + contents: read + pull-requests: read + +jobs: + dependency-review: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Review dependency changes + uses: actions/dependency-review-action@v4 + with: + fail-on-severity: high diff --git a/batllm-pr-implementation/.github/workflows/pip-audit.yml b/batllm-pr-implementation/.github/workflows/pip-audit.yml new file mode 100644 index 0000000..c515148 --- /dev/null +++ b/batllm-pr-implementation/.github/workflows/pip-audit.yml @@ -0,0 +1,28 @@ +name: Python dependency audit + +on: + pull_request: + branches: [main] + push: + branches: [main] + schedule: + - cron: "17 4 * * 1" + +permissions: + contents: read + +jobs: + pip-audit: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: "pip" + - name: Audit requirements + uses: pypa/gh-action-pip-audit@v1.1.0 + with: + inputs: requirements.txt diff --git a/batllm-pr-implementation/PR_BODY.md b/batllm-pr-implementation/PR_BODY.md new file mode 100644 index 0000000..ebc8317 --- /dev/null +++ b/batllm-pr-implementation/PR_BODY.md @@ -0,0 +1,38 @@ +## Summary + +This PR implements the confirmed high-confidence improvements from the BatLLM audit: + +- adds a repository security policy; +- adds Dependabot for Python and GitHub Actions dependencies; +- adds PR-time dependency review; +- adds scheduled and PR-time Python dependency auditing with `pip-audit`; +- adds a cross-platform Python CI matrix for Linux, macOS, and Windows; +- documents the single runtime-state invariant: installed application files are read-only and mutable state belongs under `BATLLM_HOME` or the platform app-data equivalent; +- adds a maintainer audit checklist for launchers, configuration, sessions, Ollama lifecycle, and release checks. + +## Rationale + +The audit found that BatLLM has several operational surfaces: source launchers, analyzer launchers, Homebrew packaging, release bundles, mutable configuration, saved sessions, and local Ollama orchestration. This makes repository hygiene and state-location consistency critical. + +This PR is deliberately additive. It avoids speculative refactors where source-level verification is required, but it establishes the CI/security/doc baseline needed before deeper changes such as entry-point consolidation, `pyproject.toml` migration, and state-path refactoring. + +## Verification + +Expected checks: + +```bash +python -m pip install --upgrade pip +python -m pip install -r requirements.txt +python run_tests.py +python -m compileall . +pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py +pip-audit -r requirements.txt +``` + +## Follow-up work + +- Convert runtime configuration writes to use `BATLLM_HOME` everywhere. +- Add migration logic for repository-relative historical config. +- Collapse launchers onto canonical installed entry points. +- Add `pyproject.toml` after confirming package/module names under `src/`. +- Add tests for path handling, missing Ollama, non-responsive Ollama, subprocess timeouts, and session migration. diff --git a/batllm-pr-implementation/PR_TITLE.txt b/batllm-pr-implementation/PR_TITLE.txt new file mode 100644 index 0000000..66765fe --- /dev/null +++ b/batllm-pr-implementation/PR_TITLE.txt @@ -0,0 +1 @@ +Harden CI, dependency security, and runtime state documentation diff --git a/batllm-pr-implementation/SECURITY.md b/batllm-pr-implementation/SECURITY.md new file mode 100644 index 0000000..938dfb6 --- /dev/null +++ b/batllm-pr-implementation/SECURITY.md @@ -0,0 +1,22 @@ +# Security Policy + +## Supported versions + +Security fixes are provided for the current `main` branch and the most recent tagged release. + +## Reporting a vulnerability + +Report suspected vulnerabilities privately. Do not open a public issue containing exploit details, secrets, local paths, or reproduction data that may expose a user system. + +Include: + +- affected BatLLM version or commit; +- operating system and Python version; +- installation method; +- whether Ollama was installed system-wide, through Homebrew, or manually; +- minimal reproduction steps; +- relevant logs with secrets, local usernames, and paths redacted. + +## Security-relevant areas + +BatLLM interacts with a local Ollama service, reads and writes local configuration, stores sessions, and invokes launch scripts. Reports involving path traversal, unsafe subprocess use, unexpected writes outside the configured application directory, dependency compromise, or unintended disclosure of local files should be treated as security relevant. diff --git a/batllm-pr-implementation/docs/MAINTAINER_AUDIT_CHECKLIST.md b/batllm-pr-implementation/docs/MAINTAINER_AUDIT_CHECKLIST.md new file mode 100644 index 0000000..ad9f026 --- /dev/null +++ b/batllm-pr-implementation/docs/MAINTAINER_AUDIT_CHECKLIST.md @@ -0,0 +1,28 @@ +# Maintainer audit checklist + +Use this checklist before release or after changing launch, configuration, packaging, or Ollama lifecycle code. + +## Functional checks + +- `python run_tests.py` passes on Python 3.10, 3.11, and 3.12. +- Application launch works from source checkout. +- Analyzer launch works from source checkout. +- Homebrew launcher and release-bundle launcher call the same canonical application entry path. +- Changing model selection updates only the user state directory. +- Saved sessions are written under the user state directory. +- Legacy session files either migrate deterministically or fail with a clear compatibility message. + +## Security and dependency checks + +- `pip-audit -r requirements.txt` passes or accepted findings are documented. +- Dependency Review passes on pull requests that change dependencies. +- Dependabot pull requests are reviewed and merged or explicitly rejected. +- No launcher uses untrusted shell interpolation. +- Subprocess calls use explicit argument lists, bounded timeouts, and clear error propagation. + +## Platform checks + +- Linux, macOS, and Windows CI pass. +- `BATLLM_HOME` works on all supported platforms. +- Paths with spaces and non-ASCII characters are tested. +- Missing Ollama, stopped Ollama, and non-responsive Ollama produce actionable errors. diff --git a/batllm-pr-implementation/docs/STATE_AND_INSTALLATION.md b/batllm-pr-implementation/docs/STATE_AND_INSTALLATION.md new file mode 100644 index 0000000..d44ae2c --- /dev/null +++ b/batllm-pr-implementation/docs/STATE_AND_INSTALLATION.md @@ -0,0 +1,32 @@ +# Installation channels and mutable state + +BatLLM should use one state model across all installation channels. + +## Invariant + +Installed application files are read-only at runtime. User changes must not mutate the source tree, package installation directory, Homebrew cellar, application bundle, or release-bundle program directory. + +Runtime state belongs in a per-user application directory. `BATLLM_HOME` overrides the default location and is the canonical mechanism for tests, portable bundles, and package-manager integrations. + +## State categories + +| Category | Mutable | Location | +|---|---:|---| +| Packaged defaults | No | repository/package data | +| Effective configuration | Yes | `$BATLLM_HOME/config.yaml` or platform app-data equivalent | +| Saved sessions | Yes | `$BATLLM_HOME/sessions/` | +| Logs | Yes | `$BATLLM_HOME/logs/` | +| Cache/temp files | Yes | `$BATLLM_HOME/cache/` | + +## Required behaviour + +- On first run, create the user state directory if it does not exist. +- Copy packaged default configuration into the user state directory before applying user edits. +- Treat repository-relative `src/configs/config.yaml` as a read-only default, not as runtime state. +- Prefer atomic writes for configuration and saved sessions. +- Do not write to the Homebrew cellar or any other package-manager-controlled directory. +- Tests should set `BATLLM_HOME` to a temporary directory. + +## Migration rule + +If an older install has user-edited configuration in a repository-relative path, migrate it once into the user state directory and leave the original file untouched after migration. diff --git a/batllm-pr-implementation/scripts/apply_audit_pr.sh b/batllm-pr-implementation/scripts/apply_audit_pr.sh new file mode 100755 index 0000000..34d04ad --- /dev/null +++ b/batllm-pr-implementation/scripts/apply_audit_pr.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [ ! -d .git ]; then + echo "Run this from the BatLLM repository root." >&2 + exit 1 +fi + +git checkout -b chore/audit-ci-security-state-docs +cp -R .github docs SECURITY.md PR_TITLE.txt PR_BODY.md . +git add . +git commit -m "chore: add audit-driven CI security and state documentation" + +echo "Branch created: chore/audit-ci-security-state-docs" +echo "Open the PR with:" +echo "gh pr create --title \"$(cat PR_TITLE.txt)\" --body-file PR_BODY.md" diff --git a/docs/MAINTAINER_AUDIT_CHECKLIST.md b/docs/MAINTAINER_AUDIT_CHECKLIST.md new file mode 100644 index 0000000..ad9f026 --- /dev/null +++ b/docs/MAINTAINER_AUDIT_CHECKLIST.md @@ -0,0 +1,28 @@ +# Maintainer audit checklist + +Use this checklist before release or after changing launch, configuration, packaging, or Ollama lifecycle code. + +## Functional checks + +- `python run_tests.py` passes on Python 3.10, 3.11, and 3.12. +- Application launch works from source checkout. +- Analyzer launch works from source checkout. +- Homebrew launcher and release-bundle launcher call the same canonical application entry path. +- Changing model selection updates only the user state directory. +- Saved sessions are written under the user state directory. +- Legacy session files either migrate deterministically or fail with a clear compatibility message. + +## Security and dependency checks + +- `pip-audit -r requirements.txt` passes or accepted findings are documented. +- Dependency Review passes on pull requests that change dependencies. +- Dependabot pull requests are reviewed and merged or explicitly rejected. +- No launcher uses untrusted shell interpolation. +- Subprocess calls use explicit argument lists, bounded timeouts, and clear error propagation. + +## Platform checks + +- Linux, macOS, and Windows CI pass. +- `BATLLM_HOME` works on all supported platforms. +- Paths with spaces and non-ASCII characters are tested. +- Missing Ollama, stopped Ollama, and non-responsive Ollama produce actionable errors. diff --git a/docs/STATE_AND_INSTALLATION.md b/docs/STATE_AND_INSTALLATION.md new file mode 100644 index 0000000..d44ae2c --- /dev/null +++ b/docs/STATE_AND_INSTALLATION.md @@ -0,0 +1,32 @@ +# Installation channels and mutable state + +BatLLM should use one state model across all installation channels. + +## Invariant + +Installed application files are read-only at runtime. User changes must not mutate the source tree, package installation directory, Homebrew cellar, application bundle, or release-bundle program directory. + +Runtime state belongs in a per-user application directory. `BATLLM_HOME` overrides the default location and is the canonical mechanism for tests, portable bundles, and package-manager integrations. + +## State categories + +| Category | Mutable | Location | +|---|---:|---| +| Packaged defaults | No | repository/package data | +| Effective configuration | Yes | `$BATLLM_HOME/config.yaml` or platform app-data equivalent | +| Saved sessions | Yes | `$BATLLM_HOME/sessions/` | +| Logs | Yes | `$BATLLM_HOME/logs/` | +| Cache/temp files | Yes | `$BATLLM_HOME/cache/` | + +## Required behaviour + +- On first run, create the user state directory if it does not exist. +- Copy packaged default configuration into the user state directory before applying user edits. +- Treat repository-relative `src/configs/config.yaml` as a read-only default, not as runtime state. +- Prefer atomic writes for configuration and saved sessions. +- Do not write to the Homebrew cellar or any other package-manager-controlled directory. +- Tests should set `BATLLM_HOME` to a temporary directory. + +## Migration rule + +If an older install has user-edited configuration in a repository-relative path, migrate it once into the user state directory and leave the original file untouched after migration. diff --git a/scripts/apply_audit_pr.sh b/scripts/apply_audit_pr.sh new file mode 100755 index 0000000..34d04ad --- /dev/null +++ b/scripts/apply_audit_pr.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [ ! -d .git ]; then + echo "Run this from the BatLLM repository root." >&2 + exit 1 +fi + +git checkout -b chore/audit-ci-security-state-docs +cp -R .github docs SECURITY.md PR_TITLE.txt PR_BODY.md . +git add . +git commit -m "chore: add audit-driven CI security and state documentation" + +echo "Branch created: chore/audit-ci-security-state-docs" +echo "Open the PR with:" +echo "gh pr create --title \"$(cat PR_TITLE.txt)\" --body-file PR_BODY.md" From ee4aeefe48a3c0948862d77a053dda14aed552f7 Mon Sep 17 00:00:00 2001 From: krahd Date: Wed, 27 May 2026 15:34:39 -0300 Subject: [PATCH 2/3] docs: serve SECURITY.md at /SECURITY.md for docs site completeness --- .github/workflows/ci.yml | 16 +++++++++++++--- STATUS.md | 18 +++++++++++++++--- docs/SECURITY.md | 8 ++++++++ packaging/homebrew/requirements.txt | 5 +++-- requirements.txt | 6 +++--- 5 files changed, 42 insertions(+), 11 deletions(-) create mode 100644 docs/SECURITY.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8ef0035..a9afb71 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,15 +27,25 @@ jobs: with: python-version: ${{ matrix.python-version }} cache: "pip" + - name: Create venv + run: | + python -m venv .venv_BatLLM - name: Install dependencies run: | + . .venv_BatLLM/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt python -m pip install pytest pylint - name: Compile sources - run: python -m compileall . + run: | + . .venv_BatLLM/bin/activate + python -m compileall . - name: Run tests - run: python run_tests.py + run: | + . .venv_BatLLM/bin/activate + python run_tests.py - name: Run pylint if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' }} - run: pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py + run: | + . .venv_BatLLM/bin/activate + pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py diff --git a/STATUS.md b/STATUS.md index 0180820..0a1862b 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,6 +1,6 @@ # BatLLM Status -Last updated: 2026-05-23 +Last updated: 2026-05-27 BatLLM is a Python/Kivy research, education, and game project for exploring AI-mediated play, prompt quality, LLM behaviour, and local-model workflows. The repository currently contains a playable local desktop game, a standalone read-only Game Analyzer, local Ollama lifecycle and model-management helpers routed through `modelito`, release-bundle tooling, Homebrew formula generation, generated API reference artefacts, and maintained user/developer documentation. @@ -12,7 +12,7 @@ The project should remain practical, critical, and educational. Destructive or e - Python: `>=3.10` and `<3.13` enforced by the launcher compatibility helper. - Main UI framework: Kivy `2.3.1` plus KivyMD `1.2.0`. -- LLM/runtime integration: Ollama through `modelito==1.4.0` and `ollama==0.5.3`. +- LLM/runtime integration: Ollama through `modelito==1.4.0` and `ollama>=0.5.11`. - Default shipped model: `smollm2` with first-run `last_served_model` intentionally blank. - Repository version: `0.3.6`. @@ -46,6 +46,7 @@ python run_batllm.py python run_game_analyzer.py ``` + ### Test Runner ```bash @@ -56,6 +57,17 @@ python run_tests.py full `run_tests.py full` requires `.venv_BatLLM` and may start/stop a real local Ollama service. Use it only when local Ollama state is safe to exercise. +## 2026-05-27: CI and Dependency Security Update + +- Updated `requirements.txt` to require: + - `ollama>=0.5.11` (fixes PYSEC-2025-145) + - `requests>=2.33.0` (fixes CVE-2026-25645) + - `pytest>=9.0.3` (fixes CVE-2025-71176) +- Updated `.github/workflows/ci.yml` to create `.venv_BatLLM` before installing dependencies and running tests, ensuring the correct Python interpreter is used. +- All other dependencies remain pinned as before. +- Dependency Review workflow requires enabling the GitHub Dependency Graph in repository settings for full support. +- All other project state, architecture, and documentation remain as previously described. + ### Useful Environment Variables - `BATLLM_HOME`: redirects mutable config and saved-session data away from the repository or package install location. @@ -293,4 +305,4 @@ The previous status report recorded these successful checks from the same releas - Design the 2.0 server contract before adding web or repository-backed prompt/game sharing. - Add broader tests for malformed model responses, slow startup, missing models, session compatibility, analyzer edge cases, and packaged first-run behaviour. -Last updated: 2026-05-23 +Last updated: 2026-05-27 diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 0000000..1df4e1d --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,8 @@ +# Security Policy + +This project follows responsible disclosure and dependency security best practices. See the root SECURITY.md for the canonical policy. + +- Vulnerabilities should be reported privately to the maintainer. +- Dependency and CI security are enforced via pip-audit, Dependabot, and GitHub Dependency Review. +- No secrets, credentials, or sensitive data should be committed to the repository. +- See [../SECURITY.md](../SECURITY.md) for the full policy and contact details. diff --git a/packaging/homebrew/requirements.txt b/packaging/homebrew/requirements.txt index c695738..05a2ee3 100644 --- a/packaging/homebrew/requirements.txt +++ b/packaging/homebrew/requirements.txt @@ -1,7 +1,8 @@ +modelito==1.4.0 Kivy==2.3.1 kivymd==1.2.0 Kivy-Garden==0.1.5 -ollama==0.5.3 +ollama>=0.5.11 psutil==7.0.0 PyYAML==6.0.2 -requests==2.32.4 \ No newline at end of file +requests>=2.33.0 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 6b73b63..57a7f91 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,9 +1,9 @@ Kivy==2.3.1 kivymd==1.2.0 Kivy-Garden==0.1.5 -ollama==0.5.3 +ollama>=0.5.11 psutil==7.0.0 PyYAML==6.0.2 -requests==2.32.4 -pytest==8.3.5 +requests>=2.33.0 +pytest>=9.0.3 modelito==1.4.0 From d04cee0f90e2f481e219cb45b452e3ca7944c420 Mon Sep 17 00:00:00 2001 From: krahd Date: Fri, 29 May 2026 01:57:39 -0300 Subject: [PATCH 3/3] docs: refresh status after audit merge --- STATUS.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/STATUS.md b/STATUS.md index 0a1862b..19c43ca 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,6 +1,6 @@ # BatLLM Status -Last updated: 2026-05-27 +Last updated: 2026-05-29 01:52 BatLLM is a Python/Kivy research, education, and game project for exploring AI-mediated play, prompt quality, LLM behaviour, and local-model workflows. The repository currently contains a playable local desktop game, a standalone read-only Game Analyzer, local Ollama lifecycle and model-management helpers routed through `modelito`, release-bundle tooling, Homebrew formula generation, generated API reference artefacts, and maintained user/developer documentation. @@ -57,14 +57,17 @@ python run_tests.py full `run_tests.py full` requires `.venv_BatLLM` and may start/stop a real local Ollama service. Use it only when local Ollama state is safe to exercise. -## 2026-05-27: CI and Dependency Security Update +## 2026-05-29: CI, Security, And Documentation Merge -- Updated `requirements.txt` to require: +- Fast-forwarded the audit-driven branch into `main`; the repository now includes the CI, dependency-security, and documentation artefacts listed below. +- Updated `requirements.txt` and `packaging/homebrew/requirements.txt` to require the audited minimum versions: - `ollama>=0.5.11` (fixes PYSEC-2025-145) - `requests>=2.33.0` (fixes CVE-2026-25645) - `pytest>=9.0.3` (fixes CVE-2025-71176) -- Updated `.github/workflows/ci.yml` to create `.venv_BatLLM` before installing dependencies and running tests, ensuring the correct Python interpreter is used. -- All other dependencies remain pinned as before. +- Added `.github/dependabot.yml`, `.github/workflows/dependency-review.yml`, and `.github/workflows/pip-audit.yml`; `.github/workflows/ci.yml` now creates `.venv_BatLLM` before installing dependencies and running tests. +- Added repository and docs-site security guidance in `SECURITY.md` and `docs/SECURITY.md`. +- Added `docs/STATE_AND_INSTALLATION.md` and `docs/MAINTAINER_AUDIT_CHECKLIST.md` for audit support and maintainer reference. +- Retained the audit bundle artefacts and helper script at the repository root for traceability: `batllm-audit-pr.patch`, `batllm-audit-pr-overlay.zip`, `batllm-pr-implementation/`, and `scripts/apply_audit_pr.sh`. - Dependency Review workflow requires enabling the GitHub Dependency Graph in repository settings for full support. - All other project state, architecture, and documentation remain as previously described. @@ -178,10 +181,12 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - `VERSION`: active repository version (`0.3.6`). - `requirements.txt`: root development/runtime dependency pins. - `pytest.ini`: pytest path and discovery configuration. -- `.github/workflows/`: CI and Homebrew tap publication workflows. +- `.github/workflows/`: CI, dependency-review, pip-audit, multiplatform, and Homebrew tap publication workflows; `.github/dependabot.yml` tracks dependency updates. - `run_batllm.py`: main application launcher. - `run_game_analyzer.py`: standalone Game Analyzer launcher. - `run_tests.py`: cross-platform core/full test runner. +- `SECURITY.md` and `docs/SECURITY.md`: repository and docs-site security guidance. +- `docs/STATE_AND_INSTALLATION.md` and `docs/MAINTAINER_AUDIT_CHECKLIST.md`: audit support and maintainer checklist documents. - `src/`: application, game, analyzer, utility, and test source. - `src/app.kv` and `src/view/*.kv`: Kivy layout definitions. - `src/assets/`: images, prompts, sounds, and system instructions. @@ -193,6 +198,7 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - `src/view/`: Kivy screen classes and UI helpers. - `docs/`: maintained user/developer docs, screenshots, diagrams, and generated API docs. - `packaging/homebrew/`: Homebrew distribution docs and pinned formula requirements. +- `batllm-audit-pr.patch`, `batllm-audit-pr-overlay.zip`, `batllm-pr-implementation/`, and `scripts/apply_audit_pr.sh`: audit bundle artefacts and helper script retained for traceability. - `tools/ollama_mock_server.py`: local mock server for Ollama integration smoke tests. ## Documentation State @@ -203,6 +209,9 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins - `docs/ROADMAP.md` describes 1.0 local desktop hardening and 2.0 networked-play direction using current `0.3.x` line wording. - `docs/RELEASE_CRITERIA_1_0.md` defines CI, reliability, UX, bundle, and documentation gates for a future 1.0 candidate. - `docs/CHANGELOG.md` keeps active unreleased notes on the `0.x` hold and draft 1.0 notes. +- `SECURITY.md` is the repository security policy, and `docs/SECURITY.md` mirrors that guidance for the published docs site. +- `docs/STATE_AND_INSTALLATION.md` summarises the current installation and repository state used by the audit bundle. +- `docs/MAINTAINER_AUDIT_CHECKLIST.md` records the maintainer checklist for the audit/security update. - `docs/index.html` is the static project showcase served by GitHub Pages from branch `main` and path `/docs`. - `docs/.nojekyll` keeps GitHub Pages from applying Jekyll processing to the static documentation tree. - `docs/FIRST_RUN_RELEASE_CHECKLIST.md` and `docs/UI_UNIFICATION_PLAN_1_0.md` remain release-preparation references. @@ -211,6 +220,11 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins ## Tests And Verification Status +### 2026-05-29 Merge Validation + +- No automated tests were rerun for the fast-forward merge to `main`; the branch only added dependency-floor, workflow, and documentation files. +- The validation record below remains the latest executed test evidence for the repository state. + ### Latest Commands Run For This Audit (2026-05-23 Bug Fix Audit) - Repository-wide source read: all Python files in `src/`, root launchers, `tools/`, `scripts/`, CI workflows, `requirements.txt`, `pytest.ini`, `.pylintrc`, and packaging files read and cross-referenced by three parallel agents. @@ -305,4 +319,4 @@ The previous status report recorded these successful checks from the same releas - Design the 2.0 server contract before adding web or repository-backed prompt/game sharing. - Add broader tests for malformed model responses, slow startup, missing models, session compatibility, analyzer edge cases, and packaged first-run behaviour. -Last updated: 2026-05-27 +Last updated: 2026-05-29 01:52