kiff-scan 0.1.0__tar.gz

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

@@ -0,0 +1,75 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -v
+
+  no-network:
+    name: test suite passes with no network access
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - name: Run the suite with no network access
+        # Isolate only the test process in a fresh network namespace with nothing
+        # but loopback. Dropping traffic globally (iptables -P OUTPUT DROP) would
+        # also sever the runner's own connection to GitHub and hang the job.
+        #
+        # The interpreter is resolved *before* sudo: sudo resets PATH, so
+        # resolving it inside would pick /usr/bin/python, which has no pytest.
+        run: |
+          set -euo pipefail
+          PY="$(command -v python)"
+          echo "using interpreter: $PY"
+          sudo unshare --net -- sh -c 'ip link set lo up; exec "$1" -m pytest -q' _ "$PY"
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install ruff==0.6.9
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+
+  self-scan:
+    name: kiff-scan scans itself
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e .
+      # Scanning our own source must find nothing: kiff-scan exposes no agent
+      # tools. The fixtures are excluded by .kiff-scan.json because they contain
+      # deliberately unguarded code.
+      - run: kiff-scan scan . --fail-on low

kiff_scan-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,142 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC). There is no API token stored
+# in this repository: PyPI verifies a short-lived token minted by GitHub for this
+# exact workflow file, in this exact repository and environment. Nothing to leak,
+# nothing to rotate.
+#
+# One-time setup on PyPI, before the first release:
+#   PyPI -> Your projects (or "Publishing" for a new project) -> Add a pending
+#   publisher, with:
+#     Owner:            kiff
+#     Repository:       kiff-scan
+#     Workflow name:    release.yml
+#     Environment:      pypi
+#
+# Then push a tag to publish:
+#   git tag v0.1.0 && git push origin v0.1.0
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+permissions:
+  contents: read
+
+jobs:
+  # Never publish something that does not pass its own gates. The security
+  # claims in the README are enforced by these tests, so a release that skipped
+  # them would be a release of unverified claims.
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - name: Tests
+        run: python -m pytest -v
+      - name: Security gates
+        run: python -m pytest tests/test_no_egress.py tests/test_zero_deps.py -v
+      - name: Self-scan must be clean
+        run: kiff-scan scan . --fail-on low
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - name: Tag must match the packaged version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          if [ "$tag" != "$pkg" ]; then
+            echo "tag v$tag does not match pyproject version $pkg"
+            exit 1
+          fi
+          echo "tag and version agree: $pkg"
+      - name: Wheel must declare no runtime dependencies
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/clean
+          /tmp/clean/bin/python -m pip install --quiet dist/*.whl
+          extra=$(/tmp/clean/bin/python -m pip list --format=freeze \
+            | grep -v '^kiff-scan==' | grep -v '^pip==' \
+            | grep -v '^setuptools==' | grep -v '^wheel==' || true)
+          if [ -n "$extra" ]; then
+            echo "the wheel pulled in dependencies: $extra"
+            exit 1
+          fi
+          /tmp/clean/bin/kiff-scan --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      # Publishes with PEP 740 provenance attestations by default, so a user can
+      # verify the artifact was built from this repository at this commit.
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes "See [CHANGELOG.md](./CHANGELOG.md) for what changed."

kiff_scan-0.1.0/.github/workflows/verify-claims.yml

@@ -0,0 +1,90 @@
+name: verify-claims
+
+# Every factual claim the README makes about this package is checked here. If a
+# claim stops being true, this workflow goes red before a human notices.
+#
+# The claims under test:
+#   1. Zero runtime dependencies.
+#   2. No network code anywhere in the package (no telemetry, no upload).
+#   3. The scanner never executes the code it analyses.
+#   4. Documented exit codes behave as documented.
+#   5. The version in the README install line resolves.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "0 6 * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+
+      - name: Claim - zero runtime dependencies
+        run: python -m pytest tests/test_zero_deps.py -v
+
+      - name: Claim - no egress, no telemetry, no code execution
+        run: python -m pytest tests/test_no_egress.py -v
+
+      - name: Claim - an installed wheel pulls in nothing
+        run: |
+          set -euo pipefail
+          # Build a real wheel. `pip download .` yields an sdist, not a wheel.
+          python -m pip install --quiet build
+          rm -rf /tmp/whl
+          python -m build --wheel --outdir /tmp/whl
+          python -m venv /tmp/clean
+          /tmp/clean/bin/python -m pip install --quiet /tmp/whl/*.whl
+          installed=$(/tmp/clean/bin/python -m pip list --format=freeze | grep -v '^kiff-scan==' | grep -v '^pip==' | grep -v '^setuptools==' | grep -v '^wheel==' || true)
+          if [ -n "$installed" ]; then
+            echo "installing kiff-scan pulled in: $installed"
+            exit 1
+          fi
+          /tmp/clean/bin/kiff-scan --version
+          echo "clean install contains only kiff-scan"
+
+      - name: Claim - documented exit codes
+        run: |
+          # errexit must be OFF here: these commands are *expected* to exit
+          # non-zero, and that exit code is the thing under test.
+          set +e
+
+          kiff-scan scan tests/fixtures/ungoverned_ops.py > /dev/null 2>&1
+          [ $? -eq 1 ] || { echo "expected exit 1 on findings"; exit 1; }
+
+          kiff-scan scan tests/fixtures/hooked_agent.py > /dev/null 2>&1
+          [ $? -eq 0 ] || { echo "expected exit 0 when all findings are governed"; exit 1; }
+
+          kiff-scan scan /nonexistent > /dev/null 2>&1
+          [ $? -eq 2 ] || { echo "expected exit 2 on usage error"; exit 1; }
+
+          kiff-scan scan tests/fixtures/ungoverned_ops.py --fail-on none > /dev/null 2>&1
+          [ $? -eq 0 ] || { echo "expected exit 0 with --fail-on none"; exit 1; }
+
+          echo "all documented exit codes behave as documented"
+
+      - name: Claim - SARIF output is valid JSON with the declared schema
+        run: |
+          set -euo pipefail
+          kiff-scan scan tests/fixtures --format sarif --output /tmp/out.sarif --fail-on none
+          python - <<'PY'
+          import json
+          with open("/tmp/out.sarif", encoding="utf-8") as fh:
+              doc = json.load(fh)
+          assert doc["version"] == "2.1.0", doc["version"]
+          run = doc["runs"][0]
+          declared = {r["id"] for r in run["tool"]["driver"]["rules"]}
+          for result in run["results"]:
+              assert result["ruleId"] in declared, result["ruleId"]
+          print(f"SARIF valid: {len(run['results'])} results, {len(declared)} rules")
+          PY

kiff_scan-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.sarif
+report.html
+report.json
+.DS_Store

kiff_scan-0.1.0/.kiff-scan.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "kiff-scan's own config. tests/fixtures/ contains deliberately unguarded sample code used as scanner input, so it is excluded from a scan of this repository. Without this, kiff-scan would report findings against its own test data.",
+  "exclude": [
+    "tests/fixtures/*",
+    "tests/fixtures/**"
+  ]
+}

kiff_scan-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-09-01
+
+First release.
+
+### Added
+
+- Static analysis of Python source for agent-reachable consequential actions.
+  A finding requires all three of: reachable by a model, consequential, and no
+  decision found on the analysed path.
+- Eight consequence categories, seven of them marked `state_dependent` — the
+  cases where an authorization check is necessary but not sufficient because the
+  action's safety depends on live state at the moment of execution.
+- Per-function decision detection with named evidence levels (`decorator`,
+  `call_before_sink`, `module_hook`, `call_after_sink`, `none`), including
+  lexical precedence so a guard that runs *after* the consequential call is
+  reported rather than credited.
+- Vendor-neutral guard vocabulary: roughly 30 common authorization and approval
+  function names recognised out of the box, extensible with `--guard` or config.
+- Match confidence (`call` vs `declared`), with name-only inferences capped below
+  `high` severity so they cannot fail a build on their own.
+- Bounded interprocedural analysis: calls to functions defined in the same module
+  are followed up to four hops, so a tool that delegates its destructive work to
+  a helper is still reported, with the chain named in the reason. Cycles
+  terminate, and guards inside the chain are credited so the added reach does not
+  create false positives.
+- Reporters: terminal, JSON (`schema_version: 1`), SARIF 2.1.0, and Markdown.
+- `explain FILE:LINE` for the analysed path behind one finding.
+- `--fail-on {none,low,medium,high}`, defaulting to `medium` in the CLI and
+  `none` in the GitHub Action.
+- Unsupported files are reported explicitly and never counted as clean.
+- Configuration via `.kiff-scan.json`: custom guards, custom tool decorators,
+  exclude globs, and excluded directories.
+- GitHub Action with a sticky pull request comment and SARIF upload.
+- Security gates in CI: no network-capable imports, no telemetry, no socket
+  opened during a scan, the suite passing with outbound traffic blocked, no
+  execution of analysed code, read-only on disk, and zero runtime dependencies
+  verified against a clean install of the built wheel.
+
+### Notes
+
+Python only in this release. TypeScript and Go files are reported as unsupported
+rather than skipped silently. See [docs/COVERAGE.md](./docs/COVERAGE.md) for the
+full list of what is and is not analysed, and the known limitations of decision
+detection.

kiff_scan-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/kiff/kiff-scan
+cd kiff-scan
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+There is no build step and no compilation. `pytest` should run in under a second.
+
+## The two rules that are not negotiable
+
+**1. No runtime dependencies.** `pyproject.toml`'s `dependencies` list stays
+empty. This is the property that lets a security team run kiff-scan against a
+codebase that has adopted nothing, and it is enforced by
+`tests/test_zero_deps.py`. If you believe a dependency is genuinely required,
+open an issue first — it is a product decision, not a refactor.
+
+**2. No network code.** No `socket`, `urllib`, `http`, `requests`, or anything
+that can open a connection, anywhere in the package. Also no `subprocess` and no
+`ctypes`. Enforced by `tests/test_no_egress.py`, which checks the import graph,
+runs a scan with the socket constructor sabotaged, and verifies a scan writes
+nothing.
+
+Both are checked on every push. A pull request that trips either gate will fail
+before review.
+
+## Adding a sink
+
+Sinks live in `src/kiff_scan/detectors/sinks.py`.
+
+1. Add the call's final attribute to `SINK_CALLS`, mapped to a consequence
+   category. Match the method name, not the full qualified path, so that
+   `client.delete_thing()` and `boto3.client("x").delete_thing()` both resolve.
+2. Add a case to `tests/fixtures/` and assert it in `tests/test_engine.py`.
+3. If it needs a new category, add it to `src/kiff_scan/taxonomy.py` and decide
+   `state_dependent` deliberately — see below.
+
+## Adding a guard
+
+Guards live in `src/kiff_scan/detectors/decisions.py`. Vendor neutrality is a
+design commitment: a codebase's own `authorize()` must clear a finding exactly as
+a KIFF decision does. Do not add a check that privileges KIFF over an equivalent
+in-house guard.
+
+## Deciding `state_dependent`
+
+Ask: *can this action be fully authorized, requested by a legitimate principal,
+with valid inputs, and still be the wrong thing to do because of the state of the
+world right now?*
+
+If yes, it is state-dependent (a rollback to a bad revision, a failover to the
+active region, a second refund on an unsettled order). If an authorization check
+plus input validation genuinely closes it, it is not (arbitrary shell execution).
+
+Getting this wrong in either direction misleads the reader, so justify it in the
+`why` field, which is printed in the report.
+
+## Reporting a scanner mistake
+
+A case where the scanner is wrong is the most valuable contribution. In scope:
+
+- a supported-language sink it misses
+- a recognised guard it fails to honour
+- a finding on code with no model-controlled input on the path
+- any case where it reports clean when it should not
+
+Open an issue with a minimal reproducing file. Accepted cases become permanent
+fixtures, credited by GitHub handle. Known misses stay listed even before they
+are fixed; a challenge list that only shows fixed cases is a trophy cabinet.
+
+## Style
+
+`ruff check src tests` and `ruff format --check src tests` must pass. Comments
+should explain *why*, especially where a detector is deliberately conservative —
+that reasoning is the part a future reader cannot reconstruct.
+
+## Tests
+
+New behaviour needs a test. Fixtures under `tests/fixtures/` are scanner *input*
+and must never be imported or collected; `pyproject.toml` ignores that directory
+for collection, and the repository's own `.kiff-scan.json` excludes it from a
+self-scan.

kiff_scan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KIFF
+
+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.