threatzone 1.0.0__tar.gz

threatzone-1.0.0/.actrc

@@ -0,0 +1,18 @@
+# act defaults for threatzone-python-sdk
+# Use catthehacker's medium image — ships with python, node, uv-compatible tooling.
+# "micro" is too small; "full" is multi-gigabyte. Medium is the sweet spot.
+-P ubuntu-latest=catthehacker/ubuntu:act-latest
+-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
+-P ubuntu-24.04=catthehacker/ubuntu:act-24.04
+
+# Reuse containers between runs for caching. Faster repeat runs, mirrors CI re-runs.
+--reuse
+
+# Default event context file (realistic push-to-main payload).
+--eventpath .github/act-events/push.json
+
+# Default workflow directory (same as github).
+--workflows .github/workflows/
+
+# Default branch context so github.ref resolves to main.
+--defaultbranch main

threatzone-1.0.0/.github/act-events/pull_request.json

@@ -0,0 +1,21 @@
+{
+  "action": "opened",
+  "pull_request": {
+    "number": 1,
+    "state": "open",
+    "title": "local act PR",
+    "base": {
+      "ref": "main",
+      "sha": "0000000000000000000000000000000000000000"
+    },
+    "head": {
+      "ref": "local-act-branch",
+      "sha": "0000000000000000000000000000000000000001"
+    }
+  },
+  "repository": {
+    "name": "threatzone-python-sdk",
+    "full_name": "Malwation/threatzone-python-sdk",
+    "default_branch": "main"
+  }
+}

threatzone-1.0.0/.github/act-events/push.json

@@ -0,0 +1,24 @@
+{
+  "ref": "refs/heads/main",
+  "before": "0000000000000000000000000000000000000000",
+  "after": "0000000000000000000000000000000000000001",
+  "repository": {
+    "name": "threatzone-python-sdk",
+    "full_name": "Malwation/threatzone-python-sdk",
+    "default_branch": "main",
+    "master_branch": "main"
+  },
+  "pusher": {
+    "name": "local-act",
+    "email": "local-act@threatzone.test"
+  },
+  "commits": [],
+  "head_commit": {
+    "id": "0000000000000000000000000000000000000001",
+    "message": "local act push event",
+    "author": {
+      "name": "local-act",
+      "email": "local-act@threatzone.test"
+    }
+  }
+}

threatzone-1.0.0/.github/act-events/release.json

@@ -0,0 +1,15 @@
+{
+  "action": "published",
+  "ref": "refs/tags/v1.0.0",
+  "release": {
+    "tag_name": "v1.0.0",
+    "name": "local act release v1.0.0",
+    "draft": false,
+    "prerelease": false
+  },
+  "repository": {
+    "name": "threatzone-python-sdk",
+    "full_name": "Malwation/threatzone-python-sdk",
+    "default_branch": "main"
+  }
+}

threatzone-1.0.0/.github/act-events/workflow_dispatch.json

@@ -0,0 +1,11 @@
+{
+  "inputs": {
+    "dry_run": "true"
+  },
+  "ref": "refs/heads/main",
+  "repository": {
+    "name": "threatzone-python-sdk",
+    "full_name": "Malwation/threatzone-python-sdk",
+    "default_branch": "main"
+  }
+}

threatzone-1.0.0/.github/workflows/README.md

@@ -0,0 +1,68 @@
+# Local workflow testing with `act`
+
+This SDK ships two GitHub Actions workflows:
+
+| File | Triggers | Jobs |
+|---|---|---|
+| `ci.yml` | `push` / `pull_request` on `main`,`develop`; `workflow_dispatch` | `lint`, `type-check`, `test` (Python 3.10–3.13 matrix), `build` |
+| `publish.yml` | `release: published`; `workflow_dispatch` (with `dry_run` input) | `test` (matrix), `lint`, `type-check`, `version-check`, `build`, `publish-pypi` |
+
+Both workflows are fully runnable **locally** via [`act`](https://github.com/nektos/act) so you can iterate on CI without pushing dummy commits. Everything needed for local runs is committed alongside the workflows:
+
+```
+.actrc                        # default image, --reuse, --defaultbranch main
+.github/act-events/           # realistic event payloads (push, PR, release, workflow_dispatch)
+scripts/act-ci.sh             # wrapper around `act` for ci.yml
+scripts/act-publish.sh        # wrapper around `act` for publish.yml (dry-run by default)
+```
+
+## Prerequisites
+
+1. **Docker** running locally.
+2. **`act` ≥ 0.2.87** on your PATH:
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+   sudo mv ./bin/act /usr/local/bin/act
+   act --version
+   ```
+3. First invocation will pull `catthehacker/ubuntu:act-latest` (~1 GB). Subsequent runs reuse it.
+
+## Running CI
+
+```bash
+./scripts/act-ci.sh              # run every CI job (lint + type-check + 4-python matrix + build)
+./scripts/act-ci.sh lint         # ruff check + ruff format --check
+./scripts/act-ci.sh type-check   # mypy
+./scripts/act-ci.sh test         # pytest matrix (Python 3.10 → 3.13), 4 parallel containers
+./scripts/act-ci.sh build        # uv build, wheel import smoke, artifact upload
+```
+
+The `test` job is the slowest — act spins up one container per Python version. Use `./scripts/act-ci.sh test -j test --matrix python-version:3.12` if you only want to exercise a single version.
+
+## Running Publish (dry-run)
+
+`publish.yml` gates the real PyPI upload behind `github.event.inputs.dry_run == 'false'` or a `release` event. The wrapper defaults to `workflow_dispatch` with `dry_run=true`, which means:
+
+- ✅ `lint`, `type-check`, `test` matrix, `build`, wheel-import smoke ALL run
+- ⏭ `version-check` is skipped (only runs for real `release` events)
+- ⏭ `publish-pypi` is skipped (dry-run gate)
+
+```bash
+./scripts/act-publish.sh              # dry-run: every job except publish-pypi
+./scripts/act-publish.sh build        # dry-run, single job
+./scripts/act-publish.sh --release    # simulate a real release event
+```
+
+The `--release` mode will trigger `version-check` and attempt to reach `publish-pypi` but still fails safely because no real PyPI token is wired into the local act environment.
+
+## Event payloads
+
+Every fixture under `.github/act-events/` is a realistic-enough subset of the GitHub webhook payload to let the workflow expressions (`github.event_name`, `github.ref`, `github.event.inputs.dry_run`) resolve correctly. Edit the files if a new workflow needs additional fields.
+
+## Known local-run caveats
+
+| Step | Behavior under act | Why |
+|---|---|---|
+| `actions/upload-artifact@v4` | Skipped via `if: ${{ !env.ACT }}` | v4 requires `ACTIONS_RUNTIME_TOKEN` which act cannot provide. The step runs normally on real GitHub. Consequence: `publish-pypi` under `--release` cannot find the artifact locally, but that path also can't reach PyPI without credentials so it's moot. |
+| `codecov/codecov-action@v4` | Runs, upload silently fails | Gated behind `github.event_name == 'push' && github.ref == 'refs/heads/main'` — the push event payload satisfies this but no codecov token is wired in locally. Non-fatal. |
+| `pypa/gh-action-pypi-publish@release/v1` | Never reached | Blocked by the dry-run gate; see above. |

threatzone-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,155 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+# Cancel in-progress runs on the same ref when a new commit lands
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint + format (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: ruff check
+        run: uv run ruff check src/ tests/
+
+      - name: ruff format --check
+        run: uv run ruff format --check src/ tests/
+
+  type-check:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: mypy
+        run: uv run mypy src/threatzone
+
+  test:
+    name: Unit tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+      - name: Run tests with coverage
+        if: matrix.python-version == '3.12'
+        run: |
+          uv run pytest tests/ \
+            --cov=src/threatzone \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --cov-fail-under=75
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12' && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: [lint, type-check, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Check distribution contents
+        run: |
+          ls -la dist/
+          uv run python -m zipfile -l dist/*.whl | head -30
+
+      - name: Verify wheel imports cleanly
+        run: |
+          uv run --with ./dist/*.whl python -c "
+          import threatzone
+          print(f'threatzone version: {threatzone.__version__}')
+          assert threatzone.__version__, 'version missing'
+          "
+
+      - name: Upload distribution artifacts
+        # Skip under nektos/act — upload-artifact@v4 requires ACTIONS_RUNTIME_TOKEN
+        # which act cannot provide(learned it after countless errors dear readers...). Runs normally on real GitHub.
+        if: ${{ !env.ACT }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          retention-days: 7

threatzone-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,199 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build only, do not publish"
+        required: false
+        default: "false"
+        type: choice
+        options: ["true", "false"]
+
+# Only one publish run at a time
+concurrency:
+  group: publish-${{ github.workflow }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  # Re-run the full test matrix before publishing. Never release broken code.
+  test:
+    name: Unit tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+  lint:
+    name: Lint + format (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+      - name: ruff check
+        run: uv run ruff check src/ tests/
+      - name: ruff format --check
+        run: uv run ruff format --check src/ tests/
+
+  type-check:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+      - name: mypy
+        run: uv run mypy src/threatzone
+
+  version-check:
+    name: Verify tag matches pyproject.toml version
+    runs-on: ubuntu-latest
+    # Skip version check on manual workflow_dispatch dry runs
+    if: github.event_name == 'release'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract tag version
+        id: tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          # Strip leading 'v' if present (e.g. v1.0.0 -> 1.0.0)
+          VERSION="${TAG#v}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Tag version: ${VERSION}"
+
+      - name: Extract pyproject version
+        id: pyproject
+        run: |
+          VERSION=$(grep -E '^version = "' pyproject.toml | head -1 | sed -E 's/version = "([^"]+)"/\1/')
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "pyproject version: ${VERSION}"
+
+      - name: Extract SDK module version
+        id: module
+        run: |
+          VERSION=$(grep -E '^__version__ = "' src/threatzone/__init__.py | sed -E 's/__version__ = "([^"]+)"/\1/')
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "module version: ${VERSION}"
+
+      - name: Assert all three versions match
+        run: |
+          TAG="${{ steps.tag.outputs.version }}"
+          PYPROJECT="${{ steps.pyproject.outputs.version }}"
+          MODULE="${{ steps.module.outputs.version }}"
+          if [[ "$TAG" != "$PYPROJECT" || "$TAG" != "$MODULE" ]]; then
+            echo "::error::Version mismatch: tag=$TAG pyproject=$PYPROJECT module=$MODULE"
+            exit 1
+          fi
+          echo "All three versions match: $TAG"
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: [test, lint, type-check, version-check]
+    # If version-check was skipped (workflow_dispatch), don't require it
+    if: always() && needs.test.result == 'success' && needs.lint.result == 'success' && needs.type-check.result == 'success' && (needs.version-check.result == 'success' || needs.version-check.result == 'skipped')
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Verify wheel imports cleanly
+        run: |
+          uv run --with ./dist/*.whl python -c "
+          import threatzone
+          print(f'Built threatzone version: {threatzone.__version__}')
+          assert threatzone.__version__, 'version missing'
+          "
+
+      - name: Store distribution packages
+        # Skip under nektos/act — upload-artifact@v4 requires ACTIONS_RUNTIME_TOKEN
+        # which act cannot provide. Runs normally on real GitHub.
+        if: ${{ !env.ACT }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          retention-days: 30
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build]
+    # Publish only on real releases, not dry runs
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run == 'false')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/threatzone/
+    permissions:
+      id-token: write  # Trusted publishing (OIDC)
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: false
+          verbose: true

threatzone-1.0.0/.gitignore

@@ -0,0 +1,82 @@
+# 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/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# 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/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+PLAN.md

threatzone-1.0.0/.python-version

@@ -0,0 +1 @@
+3.10

threatzone-1.0.0/LICENSE

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