openhound-github 0.20.1__tar.gz → 0.21.0__tar.gz

openhound_github-0.21.0/.dockerignore

@@ -0,0 +1,15 @@
+# Only application inputs belong in the build context.
+**
+!Dockerfile
+!.dockerignore
+!pyproject.toml
+!uv.lock
+!README.md
+!LICENSE.md
+!src/
+!src/**
+**/__pycache__/
+**/*.pyc
+**/.dlt/
+**/*.pem
+**/*.key

openhound_github-0.21.0/.github/workflows/publish-container.yml

@@ -0,0 +1,128 @@
+name: Build and publish container
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: Existing release tag to build
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: container-${{ inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: >-
+      github.repository == 'SpecterOps/openhound-github' &&
+      github.event_name == 'pull_request' &&
+      github.event.action == 'closed' &&
+      github.event.pull_request.merged == true &&
+      github.event.pull_request.base.ref == 'main'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [cli, enterprise]
+    steps:
+      - name: Validate release tag
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+            echo "Expected a release tag such as v0.20.0" >&2
+            exit 1
+          }
+
+      - name: Checkout release
+        uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+
+      - name: Set image metadata
+        id: image
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+          REPOSITORY: ${{ github.repository }}
+          TARGET: ${{ matrix.target }}
+        run: |
+          VERSION=${RELEASE_TAG#v}
+          IMAGE="ghcr.io/${REPOSITORY,,}"
+          SUFFIX=""
+          if [[ "$TARGET" == cli ]]; then SUFFIX="-cli"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=$IMAGE:$VERSION$SUFFIX" >> "$GITHUB_OUTPUT"
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build smoke-test image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: ${{ matrix.target }}
+          platforms: linux/amd64
+          load: true
+          tags: openhound-github:smoke
+          build-args: |
+            COLLECTOR_VERSION=${{ steps.image.outputs.version }}
+          cache-from: type=gha,scope=${{ matrix.target }}
+
+      - name: Verify runtime and installed collector
+        env:
+          EXPECTED_VERSION: ${{ steps.image.outputs.version }}
+        run: |
+          docker run --rm --entrypoint python -e EXPECTED_VERSION openhound-github:smoke -c '
+          import importlib.metadata as metadata
+          import os
+          import runpy
+          from unittest.mock import patch
+          import openhound_github.main
+          assert os.getuid() != 0
+          assert metadata.version("openhound-github") == os.environ["EXPECTED_VERSION"]
+          entries = metadata.entry_points(group="openhound.sources")
+          assert any(entry.name == "github" and entry.load() for entry in entries)
+          with patch.dict(os.environ, {
+              "DESTINATION__BLOODHOUNDENTERPRISE__URL": "https://example.invalid",
+              "DESTINATION__BLOODHOUNDENTERPRISE__TOKEN_ID": "smoke-test-id",
+              "DESTINATION__BLOODHOUNDENTERPRISE__TOKEN_KEY": "smoke-test-key",
+          }), patch("openhound.scheduler.service.Service", autospec=True) as service:
+              runpy.run_path("/app/src/scheduler.py", run_name="__main__")
+              assert service.call_args.kwargs["collector_name"] == "github"
+              service.return_value.start.assert_called_once_with()
+          '
+
+      - name: Verify CLI
+        if: matrix.target == 'cli'
+        run: docker run --rm openhound-github:smoke --help
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push multi-architecture image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: ${{ matrix.target }}
+          platforms: linux/amd64,linux/arm64
+          push: true
+          sbom: true
+          tags: ${{ steps.image.outputs.tag }}
+          labels: |
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ steps.image.outputs.version }}
+          build-args: |
+            COLLECTOR_VERSION=${{ steps.image.outputs.version }}
+          cache-from: type=gha,scope=${{ matrix.target }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.target }}

{openhound_github-0.20.1 → openhound_github-0.21.0}/.github/workflows/publish.yml

@@ -14,10 +14,12 @@ on:
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
   build:
+    permissions:
+      contents: read
+      id-token: write
     environment: pypi
     runs-on: ubuntu-latest
 
@@ -44,3 +46,18 @@ jobs:
 
       - name: Publish package
         run: uv publish
+
+  container:
+    needs: build
+    permissions:
+      contents: read
+      packages: write
+    if: >-
+      github.repository == 'SpecterOps/openhound-github' &&
+      github.event_name == 'pull_request' &&
+      github.event.action == 'closed' &&
+      github.event.pull_request.merged == true &&
+      github.event.pull_request.base.ref == 'main'
+    uses: ./.github/workflows/publish-container.yml
+    with:
+      tag: ${{ inputs.tag || github.ref_name }}

{openhound_github-0.20.1 → openhound_github-0.21.0}/.github/workflows/release-on-merge.yml

@@ -11,10 +11,20 @@ on:
       - "pyproject.toml"
       - "uv.lock"
       - "README.md"
+      - "Dockerfile"
+      - ".dockerignore"
+      - ".github/workflows/publish.yml"
+      - ".github/workflows/publish-container.yml"
 
 permissions:
   contents: write
   id-token: write   # This is required for requesting the JWT for the OIDC provider
+  packages: write
+
+concurrency:
+  group: release-main
+  queue: max
+  cancel-in-progress: false
 
 jobs:
 
@@ -28,18 +38,23 @@ jobs:
     #    needs: test-core
     if: github.event.pull_request.merged == true
     runs-on: ubuntu-latest
+    outputs:
+      new_version: ${{ steps.versioning.outputs.new_version }}
 
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ github.event.pull_request.merge_commit_sha }}
 
       - name: Fetch tags
         run: git fetch --tags
 
       - name: Determine next version
         id: versioning
+        env:
+          BRANCH_NAME: ${{ github.event.pull_request.head.ref }}
         run: |
           # Get latest tag or fallback
           LATEST_TAG=$(git tag --sort=-v:refname | head -n 1)
@@ -52,7 +67,6 @@ jobs:
           VERSION=${LATEST_TAG#v}
           IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
 
-          BRANCH_NAME="${{ github.event.pull_request.head.ref }}"
           echo "Merged branch: $BRANCH_NAME"
 
           if [[ "$BRANCH_NAME" == fix/* || "$BRANCH_NAME" == patch/* || "$BRANCH_NAME" == chore/* ]]; then
@@ -86,7 +100,7 @@ jobs:
 
   publish:
     needs: tag-release
-    if: github.event.pull_request.merged == true
+    if: needs.tag-release.outputs.new_version != ''
     uses: ./.github/workflows/publish.yml
     with:
       tag: ${{ needs.tag-release.outputs.new_version }}

openhound_github-0.21.0/Dockerfile

@@ -0,0 +1,35 @@
+# syntax=docker/dockerfile:1
+FROM ghcr.io/astral-sh/uv:python3.13-trixie-slim AS builder
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=0
+
+ARG COLLECTOR_VERSION
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${COLLECTOR_VERSION}
+
+WORKDIR /app
+COPY pyproject.toml uv.lock README.md LICENSE.md ./
+COPY src ./src
+RUN test -n "$COLLECTOR_VERSION"
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --no-dev --group container --frozen --no-editable
+
+FROM gcr.io/distroless/python3-debian13:nonroot AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app/.venv/lib/python3.13/site-packages \
+    LOG_CONTAINER=true \
+    RUNTIME__LOG_PATH=/app/logs \
+    DESTINATION__BLOODHOUNDENTERPRISE__COLLECTOR_NAME=github
+
+COPY --from=builder --chown=nonroot:nonroot /app /app
+WORKDIR /app
+
+FROM base AS cli
+ENTRYPOINT ["python", "-m", "openhound"]
+CMD ["--help"]
+
+FROM base AS enterprise
+ENTRYPOINT ["python", "src/scheduler.py"]

{openhound_github-0.20.1 → openhound_github-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhound-github
-Version: 0.20.1
+Version: 0.21.0
 Summary: Github collector for OpenHound
 Author-email: "jdreijer@specterops.io" <jdreijer@specterops.io>, Jared Atkinson <jatkinson@specterops.io>
 License-File: LICENSE.md
@@ -154,3 +154,78 @@ Follow the OpenHound GitHub collector docs to get started:
 - [Configure an organization GitHub App](https://bloodhound.specterops.io/openhound/collectors/github/configure-app)
 - [Configure an enterprise GitHub App](https://bloodhound.specterops.io/openhound/collectors/github/configure-enterprise-app)
 - [Configure a personal access token](https://bloodhound.specterops.io/openhound/collectors/github/configure-pat)
+
+## Container images
+
+After a release-triggering pull request merges into `main` in
+`SpecterOps/openhound-github`, the release workflow publishes the PyPI package
+first, then builds images for `linux/amd64` and `linux/arm64` in GitHub Container
+Registry. Container builds are skipped for forks, other branches, and standalone
+tag pushes. Both images use the same release version:
+
+- `ghcr.io/specterops/openhound-github:<version>` starts the BloodHound Enterprise scheduler.
+- `ghcr.io/specterops/openhound-github:<version>-cli` runs the OpenHound CLI.
+
+For example, release tag `v0.20.0` produces image tags `0.20.0` and `0.20.0-cli`.
+Use a version containing the container files; releases predating this workflow
+cannot be built without backporting those files. No moving `latest` tag is published.
+
+### Run the scheduler
+
+Prepare your `.dlt/config.toml`, `.dlt/secrets.toml`, and GitHub App private key
+following the collector configuration documentation above. Mount the directory
+read-only and use the container path for the key (for example,
+`/app/.dlt/github-app.pem`). The container runs as UID/GID `65532`; mounted
+files must be readable by that user.
+
+```sh
+docker run --rm --init \
+  --mount type=bind,src="$(pwd)/.dlt",dst=/app/.dlt,readonly \
+  ghcr.io/specterops/openhound-github:<version>
+```
+
+Set the BloodHound Enterprise destination URL, token ID, and token key in
+`.dlt/secrets.toml`:
+
+```toml
+[destination.bloodhoundenterprise]
+url = "https://<tenant>.bloodhoundenterprise.io"
+token_id = "<token-id>"
+token_key = "<token-key>"
+```
+
+The image defaults the collector name to `github`. OpenHound manages the
+scheduler polling interval internally. Collection state and output are stored
+inside the container unless you mount persistent storage for them.
+
+To inspect the CLI:
+
+```sh
+docker run --rm ghcr.io/specterops/openhound-github:<version>-cli --help
+```
+
+### Build and publish
+
+To build locally without publishing:
+
+```sh
+docker build --target cli --build-arg COLLECTOR_VERSION=0.20.0 \
+  -t openhound-github:0.20.0-cli .
+docker build --target enterprise --build-arg COLLECTOR_VERSION=0.20.0 \
+  -t openhound-github:0.20.0 .
+```
+
+`COLLECTOR_VERSION` sets the GitHub collector package version; the OpenHound
+framework version is resolved separately from `uv.lock`. The container-only
+dependency group installs the framework without development tools.
+
+To retry a failed container publication, re-run the failed jobs in the original
+release workflow run. The container workflow authenticates using `GITHUB_TOKEN`
+with `packages: write`; AWS credentials and personal access tokens are not
+needed. Runtime checks run before each image is pushed, and both architectures
+include an SBOM.
+
+After the first publication, a package administrator should verify the GHCR
+package's visibility and repository access. New packages default to private;
+make the package public if anonymous pulls are intended. If the package
+already exists, grant this repository's Actions workflows write access to it.

{openhound_github-0.20.1 → openhound_github-0.21.0}/README.md

@@ -143,3 +143,78 @@ Follow the OpenHound GitHub collector docs to get started:
 - [Configure an organization GitHub App](https://bloodhound.specterops.io/openhound/collectors/github/configure-app)
 - [Configure an enterprise GitHub App](https://bloodhound.specterops.io/openhound/collectors/github/configure-enterprise-app)
 - [Configure a personal access token](https://bloodhound.specterops.io/openhound/collectors/github/configure-pat)
+
+## Container images
+
+After a release-triggering pull request merges into `main` in
+`SpecterOps/openhound-github`, the release workflow publishes the PyPI package
+first, then builds images for `linux/amd64` and `linux/arm64` in GitHub Container
+Registry. Container builds are skipped for forks, other branches, and standalone
+tag pushes. Both images use the same release version:
+
+- `ghcr.io/specterops/openhound-github:<version>` starts the BloodHound Enterprise scheduler.
+- `ghcr.io/specterops/openhound-github:<version>-cli` runs the OpenHound CLI.
+
+For example, release tag `v0.20.0` produces image tags `0.20.0` and `0.20.0-cli`.
+Use a version containing the container files; releases predating this workflow
+cannot be built without backporting those files. No moving `latest` tag is published.
+
+### Run the scheduler
+
+Prepare your `.dlt/config.toml`, `.dlt/secrets.toml`, and GitHub App private key
+following the collector configuration documentation above. Mount the directory
+read-only and use the container path for the key (for example,
+`/app/.dlt/github-app.pem`). The container runs as UID/GID `65532`; mounted
+files must be readable by that user.
+
+```sh
+docker run --rm --init \
+  --mount type=bind,src="$(pwd)/.dlt",dst=/app/.dlt,readonly \
+  ghcr.io/specterops/openhound-github:<version>
+```
+
+Set the BloodHound Enterprise destination URL, token ID, and token key in
+`.dlt/secrets.toml`:
+
+```toml
+[destination.bloodhoundenterprise]
+url = "https://<tenant>.bloodhoundenterprise.io"
+token_id = "<token-id>"
+token_key = "<token-key>"
+```
+
+The image defaults the collector name to `github`. OpenHound manages the
+scheduler polling interval internally. Collection state and output are stored
+inside the container unless you mount persistent storage for them.
+
+To inspect the CLI:
+
+```sh
+docker run --rm ghcr.io/specterops/openhound-github:<version>-cli --help
+```
+
+### Build and publish
+
+To build locally without publishing:
+
+```sh
+docker build --target cli --build-arg COLLECTOR_VERSION=0.20.0 \
+  -t openhound-github:0.20.0-cli .
+docker build --target enterprise --build-arg COLLECTOR_VERSION=0.20.0 \
+  -t openhound-github:0.20.0 .
+```
+
+`COLLECTOR_VERSION` sets the GitHub collector package version; the OpenHound
+framework version is resolved separately from `uv.lock`. The container-only
+dependency group installs the framework without development tools.
+
+To retry a failed container publication, re-run the failed jobs in the original
+release workflow run. The container workflow authenticates using `GITHUB_TOKEN`
+with `packages: write`; AWS credentials and personal access tokens are not
+needed. Runtime checks run before each image is pushed, and both architectures
+include an SBOM.
+
+After the first publication, a package administrator should verify the GHCR
+package's visibility and repository access. New packages default to private;
+make the package public if anonymous pulls are intended. If the package
+already exists, grant this repository's Actions workflows write access to it.

{openhound_github-0.20.1 → openhound_github-0.21.0}/pyproject.toml

@@ -27,6 +27,9 @@ local_scheme = "no-local-version"
 "src/openhound_github/extension.yaml" = "openhound_github/extension.yaml"
 
 [dependency-groups]
+container = [
+    "openhound>=0.4.0",
+]
 dev = [
     "openhound>=0.4.0",
     "pre-commit>=4.5.1",

{openhound_github-0.20.1 → openhound_github-0.21.0}/src/openhound_github/models/__init__.py

@@ -7,6 +7,7 @@ from .branch_push_allowance import BranchPushAllowance
 from .classic_personal_access_token import ClassicPersonalAccessToken
 from .enterprise import Enterprise
 from .enterprise_admin import EnterpriseAdmin
+from .enterprise_credential_inventory import EnterpriseCredentialInventory
 from .enterprise_helpers import enterprise_role_node_id, enterprise_team_node_id
 from .enterprise_managed_user import EnterpriseManagedUser
 from .enterprise_member import BaseUser, flatten_enterprise_member
@@ -140,6 +141,7 @@ __all__ = [
     "DeployKey",
     "Enterprise",
     "EnterpriseAdmin",
+    "EnterpriseCredentialInventory",
     "EnterpriseManagedUser",
     "EnterpriseOrganization",
     "EnterpriseRole",

openhound_github-0.21.0/src/openhound_github/models/enterprise_credential_inventory.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class EnterpriseCredentialInventory(BaseModel):
+    """A downloaded credential export, before credential-specific parsing.
+
+    Keep CSV fields as raw values so unknown credential types and new columns
+    survive collection. DLT returns dictionaries for the downstream parser.
+    """
+
+    export_id: str
+    as_of: str | None = None
+    created_with_fallback: bool
+    columns: list[str]
+    rows: list[dict[str, Any]]
+    enterprise_node_id: str
+    enterprise_name: str

{openhound_github-0.20.1 → openhound_github-0.21.0}/src/openhound_github/resources/enterprise.py

@@ -37,6 +37,7 @@ from openhound_github.models import (
     ClassicPersonalAccessToken,
     Enterprise,
     EnterpriseAdmin,
+    EnterpriseCredentialInventory,
     EnterpriseManagedUser,
     EnterpriseOrganization,
     EnterpriseRunner,
@@ -285,7 +286,7 @@ def _download_enterprise_credential_inventory(
 
 @app.transformer(
     name="enterprise_credential_inventory",
-    columns={"columns": {"data_type": "json"}, "rows": {"data_type": "json"}},
+    columns=EnterpriseCredentialInventory,
     parallelized=True,
 )
 def enterprise_credential_inventory(enterprise_data: Enterprise, ctx: SourceContext):

openhound_github-0.21.0/src/scheduler.py

@@ -0,0 +1,25 @@
+"""Start the BloodHound Enterprise scheduler for the configured collector."""
+
+import logging
+
+import dlt
+
+from openhound.scheduler.service import Service
+
+logger = logging.getLogger(__name__)
+
+
+def start() -> None:
+    collector_name = dlt.config["destination.bloodhoundenterprise.collector_name"]
+    logger.info("Initializing service for collector '%s'.", collector_name)
+    service = Service(
+        bhe_uri=dlt.secrets["destination.bloodhoundenterprise.url"],
+        token_key=dlt.secrets["destination.bloodhoundenterprise.token_key"],
+        token_id=dlt.secrets["destination.bloodhoundenterprise.token_id"],
+        collector_name=collector_name,
+    )
+    service.start()
+
+
+if __name__ == "__main__":
+    start()

{openhound_github-0.20.1 → openhound_github-0.21.0}/tests/test_classic_personal_access_tokens.py

@@ -6,18 +6,20 @@ from types import SimpleNamespace
 from unittest.mock import MagicMock
 
 import dlt
+import duckdb
 import pytest
 import requests
-import duckdb
+from dlt.common.schema.exceptions import DataValidationError
 from dlt.destinations import filesystem
+from dlt.extract.validation import PydanticValidator
 
 from openhound_github.kinds import edges as ek
 from openhound_github.lookup import GithubLookup
 from openhound_github.models.classic_personal_access_token import (
     ClassicPersonalAccessToken,
 )
-from openhound_github.models.enterprise_member import BaseUser
 from openhound_github.models.enterprise import Enterprise
+from openhound_github.models.enterprise_member import BaseUser
 from openhound_github.resources.enterprise import (
     SourceContext,
     _download_enterprise_credential_inventory,
@@ -53,6 +55,43 @@ class Response:
             yield self.content[offset : offset + chunk_size]
 
 
+def test_inventory_validator_preserves_raw_csv_for_token_parser(monkeypatch):
+    validator = enterprise_credential_inventory.validator
+    assert isinstance(validator, PydanticValidator)
+    monkeypatch.setattr(
+        validator, "table_name", enterprise_credential_inventory.name, raising=False
+    )
+    assert enterprise_credential_inventory.columns["columns"]["data_type"] == "json"
+    assert enterprise_credential_inventory.columns["rows"]["data_type"] == "json"
+
+    inventory = {
+        "export_id": "export-1",
+        "as_of": None,
+        "created_with_fallback": False,
+        "enterprise_node_id": "E_1",
+        "enterprise_name": "enterprise",
+        "columns": ["credential_type", "credential_id", "new_csv_column"],
+        "rows": [
+            {"credential_type": "classic_pat", "credential_id": "invalid"},
+            {"credential_type": "classic_pat", "credential_id": "42"},
+            {
+                "credential_type": "future_credential_type",
+                "credential_id": "007",
+                "new_csv_column": None,
+            },
+        ],
+    }
+    validated = validator(inventory)
+    assert isinstance(validated, dict)
+    assert validated == inventory
+    tokens = list(classic_personal_access_tokens.__wrapped__(validated))
+    assert [token["credential_id"] for token in tokens] == [42]
+
+    # Validate the envelope without applying credential-specific rules to CSV rows.
+    with pytest.raises(DataValidationError):
+        validator({**inventory, "rows": "not a list of rows"})
+
+
 def test_classic_pat_export_polls_one_job_and_deduplicates_org_rows(monkeypatch):
     client = MagicMock()
     client.post.return_value = Response(
@@ -180,6 +219,7 @@ def test_one_export_persists_raw_rows_and_models_only_classic_pats(
         return {
             "export_id": "export-1",
             "as_of": "2026-10-05T20:00:00Z",
+            "created_with_fallback": False,
             "columns": ["credential_type", "credential_id", "hashed_token"],
             "rows": [
                 {

{openhound_github-0.20.1 → openhound_github-0.21.0}/uv.lock

@@ -879,6 +879,9 @@ dependencies = [
 ]
 
 [package.dev-dependencies]
+container = [
+    { name = "openhound" },
+]
 dev = [
     { name = "mypy" },
     { name = "openhound" },
@@ -895,6 +898,9 @@ requires-dist = [
 ]
 
 [package.metadata.requires-dev]
+container = [
+    { name = "openhound", specifier = ">=0.4.0" },
+]
 dev = [
     { name = "mypy", specifier = ">=1.19.1" },
     { name = "openhound", specifier = ">=0.4.0" },