openhound-github 0.18.0__tar.gz → 0.19.0__tar.gz

{openhound_github-0.18.0 → openhound_github-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhound-github
-Version: 0.18.0
+Version: 0.19.0
 Summary: Github collector for OpenHound
 Author-email: "jdreijer@specterops.io" <jdreijer@specterops.io>, Jared Atkinson <jatkinson@specterops.io>
 License-File: LICENSE.md
@@ -84,6 +84,22 @@ The collector runs successfully with the documented read-only permission set. So
 
 If these optional permissions are not granted, OpenHound skips the affected resources and continues collecting the rest of the GitHub environment.
 
+### Selected GitHub App installation repositories
+
+For organization installations limited to selected repositories, the collector
+uses the enterprise installation's read-only organization-installation
+repositories API to create exact `GH_CanAccess` edges. Grant the enterprise
+installation **Enterprise organization installations: read** or **Enterprise
+organization installation repositories: read**. Without either permission,
+selected-repository edges are skipped; installations set to `all` continue to
+use the collected organization repository inventory.
+
+Installation discovery still uses each organization's API and requires
+**Organization administration: read** on that organization's credential. The
+enterprise permission alone does not discover installations.
+The selected-repository lookup runs one installation at a time and stops for
+the rest of a collection if GitHub rate-limits it after retries.
+
 ### Classic personal access token inventory
 
 With GitHub Enterprise Cloud credentials, the collector uses the enterprise

{openhound_github-0.18.0 → openhound_github-0.19.0}/README.md

@@ -73,6 +73,22 @@ The collector runs successfully with the documented read-only permission set. So
 
 If these optional permissions are not granted, OpenHound skips the affected resources and continues collecting the rest of the GitHub environment.
 
+### Selected GitHub App installation repositories
+
+For organization installations limited to selected repositories, the collector
+uses the enterprise installation's read-only organization-installation
+repositories API to create exact `GH_CanAccess` edges. Grant the enterprise
+installation **Enterprise organization installations: read** or **Enterprise
+organization installation repositories: read**. Without either permission,
+selected-repository edges are skipped; installations set to `all` continue to
+use the collected organization repository inventory.
+
+Installation discovery still uses each organization's API and requires
+**Organization administration: read** on that organization's credential. The
+enterprise permission alone does not discover installations.
+The selected-repository lookup runs one installation at a time and stops for
+the rest of a collection if GitHub rate-limits it after retries.
+
 ### Classic personal access token inventory
 
 With GitHub Enterprise Cloud credentials, the collector uses the enterprise

{openhound_github-0.18.0 → openhound_github-0.19.0}/descriptions/nodes/GH_AppInstallation.md

@@ -6,7 +6,7 @@ Represents a GitHub App installed on an organization. App installations have spe
 
 Unlike fine-grained personal access tokens, GitHub does not expose separate organization and repository permission buckets for app installations, so this property remains a single flat permission list.
 
-Each installation is linked to its parent GH_App via a GH_InstalledAs edge. For installations with `repository_selection` set to `all`, GH_CanAccess edges are created to every repository in the organization. For installations with `repository_selection` set to `selected`, repository-level edges cannot be enumerated with a PAT (requires app installation token authentication).
+Each installation is linked to its parent GH_App via a GH_InstalledAs edge. For installations with `repository_selection` set to `all`, GH_CanAccess edges are created to every collected repository in the organization. For installations with `repository_selection` set to `selected`, the collector uses the enterprise organization-installation repositories API to enumerate the granted repositories when the enterprise installation has `Enterprise organization installations: read` or `Enterprise organization installation repositories: read`. If that permission is unavailable, selected repository edges are skipped.
 
 ## Properties
 

{openhound_github-0.18.0 → openhound_github-0.19.0}/src/openhound_github/lookup.py

@@ -597,6 +597,16 @@ class GithubLookup(LookupManager):
             [org_login],
         )
 
+    @lru_cache
+    def repository_node_id_for_database_id(
+        self, database_id: int, org_login: str
+    ) -> str | None:
+        """Resolve a repository node by database ID within its organization."""
+        return self._find_single_object(
+            f"SELECT node_id FROM {self.schema}.repositories WHERE database_id = ? AND lower(org_login) = lower(?) LIMIT 1",
+            [database_id, org_login],
+        )
+
     @lru_cache
     def private_repository_node_ids(self):
         return self._find_all_objects(

{openhound_github-0.18.0 → openhound_github-0.19.0}/src/openhound_github/models/app_installation.py

@@ -320,7 +320,9 @@ class AppInstallationRepoAccess(BaseAsset):
     """One record from `app_installation_repo_access` → GH_CanAccess edge. No node."""
 
     installation_node_id: str
-    repo_node_id: str
+    repository_database_id: int
+    repo_full_name: str | None = None
+    org_login: str
 
     @property
     def as_node(self):
@@ -328,11 +330,17 @@ class AppInstallationRepoAccess(BaseAsset):
 
     @property
     def edges(self) -> list[Edge]:
+        """Link the installation to a collected repository when it resolves."""
+        repo_node_id = self._lookup.repository_node_id_for_database_id(
+            self.repository_database_id, self.org_login
+        )
+        if not repo_node_id:
+            return []
         return [
             Edge(
                 kind=ek.CAN_ACCESS,
                 start=EdgePath(value=self.installation_node_id, match_by="id"),
-                end=EdgePath(value=self.repo_node_id, match_by="id"),
+                end=EdgePath(value=repo_node_id, match_by="id"),
                 properties=EdgeProperties(traversable=False),
             )
         ]

{openhound_github-0.18.0 → openhound_github-0.19.0}/src/openhound_github/resources/enterprise.py

@@ -73,6 +73,14 @@ _CREDENTIAL_EXPORT_TIMEOUT_SECONDS = 300
 _CREDENTIAL_EXPORT_REUSE_SECONDS = 24 * 60 * 60
 
 
+class _CredentialExportFailed(ValueError):
+    """The export job reported a terminal failed status."""
+
+
+class _CredentialExportNotFound(requests.HTTPError):
+    """The export-status endpoint no longer recognizes a saved export ID."""
+
+
 @dataclass
 class SourceContext:
     """Shared context for GitHub API access."""
@@ -215,8 +223,13 @@ def _download_enterprise_credential_inventory(
     deadline = time.monotonic() + _CREDENTIAL_EXPORT_TIMEOUT_SECONDS
     export_path = f"{path}/{export_id}"
     while True:
-        response = client.get(export_path, headers=headers, allow_redirects=False)
-        response.raise_for_status()
+        try:
+            response = client.get(export_path, headers=headers, allow_redirects=False)
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            if exc.response is not None and exc.response.status_code == 404:
+                raise _CredentialExportNotFound(response=exc.response) from exc
+            raise
         if response.status_code == 302:
             download_url = response.headers.get("Location")
             parsed_url = urlparse(download_url or "")
@@ -259,6 +272,10 @@ def _download_enterprise_credential_inventory(
         polled_metadata = response.json()
         export_metadata.update(polled_metadata)
         status = polled_metadata.get("status")
+        if status == "failed":
+            raise _CredentialExportFailed(
+                "Credential export did not complete: 'failed'"
+            )
         if status not in {"queued", "started", "in_progress", "processing", "pending"}:
             raise ValueError(f"Credential export did not complete: {status!r}")
         if time.monotonic() >= deadline:
@@ -316,7 +333,7 @@ def enterprise_credential_inventory(enterprise_data: Enterprise, ctx: SourceCont
                 }
                 return
             except requests.HTTPError as exc:
-                if exc.response is None or exc.response.status_code != 404:
+                if not isinstance(exc, _CredentialExportNotFound):
                     logger.warning(
                         "Skipping credential inventory for enterprise '%s': prior export %s unavailable (HTTP %s)",
                         ctx.enterprise_name,
@@ -326,11 +343,20 @@ def enterprise_credential_inventory(enterprise_data: Enterprise, ctx: SourceCont
                         else "unknown",
                     )
                     return
+                state.pop("last_export_id", None)
                 logger.info(
                     "Prior credential export %s is no longer available for enterprise '%s'; creating a new export",
                     previous_id,
                     ctx.enterprise_name,
                 )
+            except _CredentialExportFailed:
+                state.pop("last_export_id", None)
+                logger.warning(
+                    "Skipping credential inventory for enterprise '%s': prior export %s failed",
+                    ctx.enterprise_name,
+                    previous_id,
+                )
+                return
             except (
                 requests.RequestException,
                 ValueError,

{openhound_github-0.18.0 → openhound_github-0.19.0}/src/openhound_github/resources/organization.py

@@ -23,6 +23,10 @@ from openhound_github.graphql import (
     TEAM_MEMBERS_OVERFLOW_QUERY,
     TEAMS_QUERY,
 )
+from openhound_github.github_retry import (
+    is_primary_rate_limit_response,
+    is_secondary_rate_limit_response,
+)
 from openhound_github.helpers import (
     AdaptiveGraphQLPageError,
     DEFAULT_GITHUB_REST_API_URL,
@@ -36,6 +40,7 @@ from openhound_github.models import (
     ActionPermission,
     App,
     AppInstallation,
+    AppInstallationRepoAccess,
     BaseRepoRole,
     Branch,
     BranchProtectionRule,
@@ -117,6 +122,7 @@ class SourceContext:
     deployment_type: str = "unknown"
     ghes_version: str | None = None
     enterprise_version_header: str | None = None
+    selected_installation_repo_access_stopped: bool = False
     cache_lock: Lock = field(default_factory=Lock)
     organizations_cache: dict[str, dict[str, Any]] = field(default_factory=dict)
     app_cache: dict[str, dict[str, Any]] = field(default_factory=dict)
@@ -655,6 +661,82 @@ def app_installations(ctx: SourceContext):
             continue
 
 
+@app.transformer(
+    name="app_installation_repo_access",
+    columns=AppInstallationRepoAccess,
+    parallelized=False,
+)
+def app_installation_repo_access(app_install: AppInstallation, ctx: SourceContext):
+    """List the repositories granted to a selected organization installation."""
+    if (
+        app_install.repository_selection != "selected"
+        or not ctx.client
+        or not ctx.enterprise_name
+        or ctx.deployment_type == "ghes"
+        or ctx.selected_installation_repo_access_stopped
+    ):
+        return
+
+    path = (
+        f"/enterprises/{ctx.enterprise_name}/apps/organizations/"
+        f"{app_install.org_login}/installations/{app_install.id}/repositories"
+    )
+    try:
+        # Read every page before yielding so a failed page cannot create partial access.
+        repositories = [
+            repository
+            for page in ctx.client.paginate(
+                path,
+                params={"per_page": 100},
+                headers={"X-GitHub-Api-Version": "2026-03-10"},
+            )
+            for repository in page
+        ]
+    except requests.HTTPError as exc:
+        response = exc.response
+        if response is not None and (
+            response.status_code == 429
+            or is_primary_rate_limit_response(response)
+            or is_secondary_rate_limit_response(response)
+            or (response.status_code == 403 and response.headers.get("Retry-After"))
+        ):
+            ctx.selected_installation_repo_access_stopped = True
+            logger.warning(
+                "GitHub rate-limited selected app installation repository access; "
+                "skipping remaining installations in this collection"
+            )
+            return
+        logger.warning(
+            "Skipping repository access for app installation %s in organization '%s': %s",
+            app_install.id,
+            app_install.org_login,
+            exc,
+        )
+        return
+    except Exception as exc:
+        logger.warning(
+            "Skipping repository access for app installation %s in organization '%s': %s",
+            app_install.id,
+            app_install.org_login,
+            exc,
+        )
+        return
+
+    for repository in repositories:
+        if repository.get("id") is None:
+            logger.warning(
+                "Skipping repository without an id for app installation %s",
+                app_install.id,
+            )
+            continue
+        yield {
+            "installation_node_id": app_install.node_id,
+            "repository_database_id": repository["id"],
+            "repo_full_name": repository.get("full_name"),
+            "org_login": app_install.org_login,
+        }
+
+
 @app.transformer(name="applications", columns=App, parallelized=True)
 def applications(app_install: AppInstallation, ctx: SourceContext):
     """Fetch full GitHub App details for an installed app.
@@ -2368,6 +2450,7 @@ def org_scim_organizations(org: Organization, ctx: SourceContext):
 
 
 def organization_resources(ctx: SourceContext):
+    """Assemble organization resources, including selected installation access."""
     org_resource = organizations(ctx)
     roles_resource = org_roles(ctx)
     repo_roles_base = RepositoryRoleCache(ctx)
@@ -2397,6 +2480,7 @@ def organization_resources(ctx: SourceContext):
         org_resource | roles_resource | org_role_teams(ctx),
         org_resource | roles_resource | org_role_members(ctx),
         app_installs_resource,
+        app_installs_resource | app_installation_repo_access(ctx),
         app_installs_resource | applications(ctx),
         users(ctx),
         actions_permissions(ctx),

{openhound_github-0.18.0 → openhound_github-0.19.0}/src/openhound_github/source.py

@@ -170,6 +170,7 @@ class SourceContext:
     deployment_type: str = "unknown"
     ghes_version: str | None = None
     enterprise_version_header: str | None = None
+    selected_installation_repo_access_stopped: bool = False
     cache_lock: Lock = field(default_factory=Lock)
     organizations_cache: dict[str, dict[str, Any]] = field(default_factory=dict)
     app_cache: dict[str, dict[str, Any]] = field(default_factory=dict)

openhound_github-0.19.0/tests/test_app_installation_repo_access.py

@@ -0,0 +1,130 @@
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import duckdb
+from requests import HTTPError, Response
+
+from openhound_github.lookup import GithubLookup
+from openhound_github.models.app_installation import AppInstallationRepoAccess
+from openhound_github.resources.organization import (
+    SourceContext,
+    app_installation_repo_access,
+)
+
+
+def _installation(selection="selected"):
+    """Build a minimal installation for repository access tests."""
+    return SimpleNamespace(
+        id=42,
+        node_id="GH_AppInstallation_42",
+        org_login="example-org",
+        repository_selection=selection,
+    )
+
+
+def test_selected_installation_lists_all_pages_with_enterprise_client():
+    """Collect every page of repositories granted to a selected installation."""
+    client = MagicMock()
+    client.paginate.return_value = [
+        [{"id": 101, "name": "one", "full_name": "example-org/one"}],
+        [{"id": 102, "name": "two", "full_name": "example-org/two"}],
+    ]
+    ctx = SourceContext(
+        client=client, enterprise_name="enterprise", deployment_type="ghec"
+    )
+
+    rows = list(app_installation_repo_access.__wrapped__(_installation(), ctx))
+
+    assert rows == [
+        {
+            "installation_node_id": "GH_AppInstallation_42",
+            "repository_database_id": 101,
+            "repo_full_name": "example-org/one",
+            "org_login": "example-org",
+        },
+        {
+            "installation_node_id": "GH_AppInstallation_42",
+            "repository_database_id": 102,
+            "repo_full_name": "example-org/two",
+            "org_login": "example-org",
+        },
+    ]
+    client.paginate.assert_called_once_with(
+        "/enterprises/enterprise/apps/organizations/example-org/"
+        "installations/42/repositories",
+        params={"per_page": 100},
+        headers={"X-GitHub-Api-Version": "2026-03-10"},
+    )
+
+
+def test_all_repositories_do_not_need_extra_request():
+    """Skip the repository lookup when an installation already selects all."""
+    client = MagicMock()
+    ctx = SourceContext(
+        client=client, enterprise_name="enterprise", deployment_type="ghec"
+    )
+
+    assert list(app_installation_repo_access.__wrapped__(_installation("all"), ctx)) == []
+    client.paginate.assert_not_called()
+
+
+def test_failed_later_page_does_not_emit_partial_access(caplog):
+    """Discard earlier pages if a later page fails."""
+    client = MagicMock()
+
+    def pages(*args, **kwargs):
+        """Yield one page before simulating a pagination failure."""
+        yield [{"id": 101, "full_name": "example-org/one"}]
+        raise PermissionError("403 Forbidden")
+
+    client.paginate.side_effect = pages
+    ctx = SourceContext(
+        client=client, enterprise_name="enterprise", deployment_type="ghec"
+    )
+
+    assert list(app_installation_repo_access.__wrapped__(_installation(), ctx)) == []
+    assert "Skipping repository access" in caplog.text
+
+
+def test_rate_limit_stops_remaining_selected_installation_requests(caplog):
+    """Stop further selected-installation lookups after a rate limit."""
+    response = Response()
+    response.status_code = 429
+    error = HTTPError("429 Too Many Requests", response=response)
+    client = MagicMock()
+    client.paginate.side_effect = error
+    ctx = SourceContext(
+        client=client, enterprise_name="enterprise", deployment_type="ghec"
+    )
+
+    assert list(app_installation_repo_access.__wrapped__(_installation(), ctx)) == []
+    assert list(app_installation_repo_access.__wrapped__(_installation(), ctx)) == []
+
+    client.paginate.assert_called_once()
+    assert ctx.selected_installation_repo_access_stopped is True
+    assert "skipping remaining installations" in caplog.text
+
+
+def test_selected_repository_id_resolves_to_access_edge():
+    """Resolve repository access within the installation organization."""
+    connection = duckdb.connect(":memory:")
+    connection.execute("CREATE SCHEMA github")
+    connection.execute(
+        "CREATE TABLE github.repositories (node_id VARCHAR, database_id BIGINT, org_login VARCHAR)"
+    )
+    connection.execute(
+        "INSERT INTO github.repositories VALUES ('R_1', 101, 'example-org'), ('R_2', 101, 'other-org')"
+    )
+    access = AppInstallationRepoAccess(
+        installation_node_id="GH_AppInstallation_42",
+        repository_database_id=101,
+        org_login="example-org",
+    )
+    access._lookup = GithubLookup(connection)
+
+    edges = access.edges
+
+    assert len(edges) == 1
+    assert edges[0].start.value == "GH_AppInstallation_42"
+    assert edges[0].end.value == "R_1"
+    assert edges[0].properties.traversable is False

{openhound_github-0.18.0 → openhound_github-0.19.0}/tests/test_classic_personal_access_tokens.py

@@ -444,7 +444,10 @@ def test_classic_pat_inventory_resumes_export_after_download_failure(
         app_client.get.assert_not_called()
 
 
-def test_classic_pat_cached_export_error_does_not_log_download_url(monkeypatch, caplog):
+@pytest.mark.parametrize("status_code", [404, 503])
+def test_classic_pat_cached_export_error_does_not_log_download_url(
+    monkeypatch, caplog, status_code
+):
     """Keep signed download URLs out of cached-export error logs."""
     state = {
         "last_export_id": "prior-1",
@@ -460,7 +463,7 @@ def test_classic_pat_cached_export_error_does_not_log_download_url(monkeypatch,
     signed_url = "https://example.test/export.csv?secret=signed-download-token"
     client.get.return_value = Response(302, headers={"Location": signed_url})
     failed_response = requests.Response()
-    failed_response.status_code = 503
+    failed_response.status_code = status_code
     failed_response.url = signed_url
     failed_response._content = b""
     monkeypatch.setattr(
@@ -477,8 +480,9 @@ def test_classic_pat_cached_export_error_does_not_log_download_url(monkeypatch,
         )
         == []
     )
-    assert "HTTP 503" in caplog.text
+    assert f"HTTP {status_code}" in caplog.text
     assert "signed-download-token" not in caplog.text
+    assert state["last_export_id"] == "prior-1"
     client.post.assert_not_called()
 
 
@@ -596,13 +600,14 @@ def test_classic_pat_inventory_reuses_recent_export_before_creating(monkeypatch)
 
 
 def test_classic_pat_inventory_creates_export_when_recent_one_is_gone(monkeypatch):
+    state = {
+        "last_export_id": "prior-1",
+        "last_export_enterprise": "enterprise",
+        "last_export_downloaded_at": 1000,
+    }
     monkeypatch.setattr(
         "openhound_github.resources.enterprise.dlt.current.resource_state",
-        lambda _: {
-            "last_export_id": "prior-1",
-            "last_export_enterprise": "enterprise",
-            "last_export_downloaded_at": 1000,
-        },
+        lambda _: state,
     )
     monkeypatch.setattr("openhound_github.resources.enterprise.time.time", lambda: 1001)
     client = MagicMock()
@@ -623,9 +628,68 @@ def test_classic_pat_inventory_creates_export_when_recent_one_is_gone(monkeypatc
         enterprise_credential_inventory.__wrapped__(SimpleNamespace(id="E_1"), ctx)
     )
     assert inventories[0]["export_id"] == "new-1"
+    assert state["last_export_id"] == "new-1"
     client.post.assert_called_once()
 
 
+def test_classic_pat_inventory_discards_missing_prior_export(monkeypatch):
+    """Clear a missing export ID even if creating its replacement fails."""
+    state = {
+        "last_export_id": "prior-1",
+        "last_export_enterprise": "enterprise",
+        "last_export_created_at": 1000,
+    }
+    monkeypatch.setattr(
+        "openhound_github.resources.enterprise.dlt.current.resource_state",
+        lambda _: state,
+    )
+    monkeypatch.setattr("openhound_github.resources.enterprise.time.time", lambda: 1001)
+    client = MagicMock()
+    client.get.return_value = Response(404)
+    client.post.return_value = Response(429)
+    ctx = SourceContext(
+        client=client, enterprise_name="enterprise", deployment_type="ghec"
+    )
+
+    assert (
+        list(
+            enterprise_credential_inventory.__wrapped__(SimpleNamespace(id="E_1"), ctx)
+        )
+        == []
+    )
+    assert "last_export_id" not in state
+    client.post.assert_called_once()
+
+
+@pytest.mark.parametrize("status", ["failed", "unknown"])
+def test_classic_pat_inventory_only_discards_failed_prior_export(monkeypatch, status):
+    """Keep a saved ID for unexpected statuses but discard a failed export."""
+    state = {
+        "last_export_id": "prior-1",
+        "last_export_enterprise": "enterprise",
+        "last_export_created_at": 1000,
+    }
+    monkeypatch.setattr(
+        "openhound_github.resources.enterprise.dlt.current.resource_state",
+        lambda _: state,
+    )
+    monkeypatch.setattr("openhound_github.resources.enterprise.time.time", lambda: 1001)
+    client = MagicMock()
+    client.get.return_value = Response(200, payload={"status": status})
+    ctx = SourceContext(
+        client=client, enterprise_name="enterprise", deployment_type="ghec"
+    )
+
+    assert (
+        list(
+            enterprise_credential_inventory.__wrapped__(SimpleNamespace(id="E_1"), ctx)
+        )
+        == []
+    )
+    assert state.get("last_export_id") == (None if status == "failed" else "prior-1")
+    client.post.assert_not_called()
+
+
 def test_classic_pat_inventory_reuses_pat_created_export_with_pat(monkeypatch):
     state = {}
     monkeypatch.setattr(
@@ -747,7 +811,7 @@ def test_classic_pat_failed_export_produces_no_partial_inventory(caplog):
         )
         == []
     )
-    assert "ValueError" in caplog.text
+    assert "CredentialExportFailed" in caplog.text
     client.post.assert_called_once()