openhound-github 0.5.0__tar.gz → 0.5.2__tar.gz

{openhound_github-0.5.0 → openhound_github-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhound-github
-Version: 0.5.0
+Version: 0.5.2
 Summary: Github collector for OpenHound
 Author-email: "jdreijer@specterops.io" <jdreijer@specterops.io>, Jared Atkinson <jatkinson@specterops.io>
 License-File: LICENSE.md
@@ -45,6 +45,12 @@ The openhound-github extension collects resources from Github organizations and
 edges for
 BloodHound.
 
+### GitHub App JWT issuer
+
+Enterprise GitHub App credentials accept either `client_id` or `app_id` as the
+JWT issuer. When both are configured, `client_id` is preferred. At least one
+identifier must be supplied together with `key_path` and `enterprise_name`.
+
 ### Enterprise SCIM and hybrid correlations
 
 When `SOURCES__GITHUB__COLLECT_ENTERPRISE_SCIM=true`, a token with enterprise SCIM access is used to collect both `/scim/v2/enterprises/{enterprise}/Users` and `/scim/v2/enterprises/{enterprise}/Groups`. The collector emits normalized `SCIM_Organization`, `SCIM_User`, and `SCIM_Group` nodes plus `SCIM_Contains`, `SCIM_MemberOf`, and `SCIM_Provisioned` relationships. Install the BloodHound SCIM extension alongside this extension to register the shared SCIM kinds.

{openhound_github-0.5.0 → openhound_github-0.5.2}/README.md

@@ -34,6 +34,12 @@ The openhound-github extension collects resources from Github organizations and
 edges for
 BloodHound.
 
+### GitHub App JWT issuer
+
+Enterprise GitHub App credentials accept either `client_id` or `app_id` as the
+JWT issuer. When both are configured, `client_id` is preferred. At least one
+identifier must be supplied together with `key_path` and `enterprise_name`.
+
 ### Enterprise SCIM and hybrid correlations
 
 When `SOURCES__GITHUB__COLLECT_ENTERPRISE_SCIM=true`, a token with enterprise SCIM access is used to collect both `/scim/v2/enterprises/{enterprise}/Users` and `/scim/v2/enterprises/{enterprise}/Groups`. The collector emits normalized `SCIM_Organization`, `SCIM_User`, and `SCIM_Group` nodes plus `SCIM_Contains`, `SCIM_MemberOf`, and `SCIM_Provisioned` relationships. Install the BloodHound SCIM extension alongside this extension to register the shared SCIM kinds.

{openhound_github-0.5.0 → openhound_github-0.5.2}/src/openhound_github/auth.py

@@ -27,7 +27,7 @@ class AccountConfig(BaseModel):
 
 class InstallationResponse(BaseModel):
     id: int
-    client_id: str
+    client_id: str | None = None
     account: AccountConfig
     target_type: str
     app_id: int | None = None
@@ -39,15 +39,32 @@ class TokenResponse(BaseModel):
     expires_at: datetime
 
 
+def resolve_github_app_jwt_issuer(
+    *, client_id: str | None, app_id: str | int | None
+) -> str:
+    """Select the configured identifier for GitHub App JWT authentication."""
+    normalized_client_id = str(client_id).strip() if client_id is not None else ""
+    if normalized_client_id:
+        return normalized_client_id
+
+    normalized_app_id = str(app_id).strip() if app_id is not None else ""
+    if normalized_app_id:
+        return normalized_app_id
+
+    raise ValueError(
+        "GitHub App credentials require either client_id or app_id for the JWT issuer"
+    )
+
+
 class GithubSession:
     def __init__(
         self,
-        client_id: str,
+        jwt_issuer: str,
         private_key_path: str,
         api_uri: str = "https://api.github.com/",
     ):
         self.api_uri = api_uri
-        self.client_id = client_id
+        self.jwt_issuer = jwt_issuer
         self.private_key_path = private_key_path
         self.client = RESTClient(
             base_url=self.api_uri,
@@ -59,9 +76,11 @@ class GithubSession:
         now_utc = datetime.now(timezone.utc).timestamp()
         header = {"alg": "RS256", "typ": "JWT"}
         claims = {
-            "iss": self.client_id,
+            "iss": self.jwt_issuer,
             "iat": int(now_utc - 10),  # Issued 10 seconds in the past
-            "exp": int(now_utc + 540),  # Expires in 9 minutes (GitHub max is 10, leaving room for clock drift)
+            "exp": int(
+                now_utc + 540
+            ),  # Expires in 9 minutes (GitHub max is 10, leaving room for clock drift)
         }
 
         try:
@@ -86,12 +105,12 @@ class GithubInstallation(GithubSession):
     def __init__(
         self,
         installation_id: str,
-        client_id: str,
+        jwt_issuer: str,
         private_key_path: str,
         api_uri: str = "https://api.github.com/",
     ):
         self.installation_id = installation_id
-        super().__init__(client_id, private_key_path, api_uri)
+        super().__init__(jwt_issuer, private_key_path, api_uri)
 
     @property
     def token(self) -> TokenResponse:
@@ -108,14 +127,11 @@ class GithubInstallation(GithubSession):
 class GithubApp(GithubSession):
     def __init__(
         self,
-        client_id: str,
+        jwt_issuer: str,
         private_key_path: str,
         api_uri: str = "https://api.github.com/",
     ):
-        self.client_id = client_id
-        self.private_key_path = private_key_path
-        self.api_uri = api_uri
-        super().__init__(client_id, private_key_path, api_uri)
+        super().__init__(jwt_issuer, private_key_path, api_uri)
 
     @property
     def installations(self) -> Iterator[InstallationResponse]:

{openhound_github-0.5.0 → openhound_github-0.5.2}/src/openhound_github/resources/organization.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from threading import Lock
 from typing import Any, Iterator
+from urllib.parse import quote
 
 from dlt.sources.helpers import requests
 from dlt.sources.helpers.rest_client.client import RESTClient
@@ -131,6 +132,10 @@ def _client_for_org(ctx: SourceContext, org_login: str) -> RESTClient:
     return ctx.client
 
 
+def _encode_path_segment(value: str) -> str:
+    return quote(value, safe="")
+
+
 def _repository_roles(ctx: SourceContext) -> list[dict[str, Any]]:
     roles: list[dict[str, Any]] = []
     for org in ctx.organizations:
@@ -1297,6 +1302,7 @@ def environment_variables(environment: Environment, ctx: SourceContext):
         EnvironmentVariable (EnvironmentVariable): Environment variable record.
     """
     env_name = environment.name
+    encoded_env_name = _encode_path_segment(env_name)
     env_node_id = environment.node_id
 
     full_repo_name = environment.repository_full_name
@@ -1305,7 +1311,7 @@ def environment_variables(environment: Environment, ctx: SourceContext):
 
     client = _client_for_org(ctx, environment.org_login)
     for page in client.paginate(
-        f"/repos/{full_repo_name}/environments/{env_name}/variables"
+        f"/repos/{full_repo_name}/environments/{encoded_env_name}/variables"
     ):
         for item in page:
             yield {
@@ -1341,10 +1347,11 @@ def environment_branch_policies(environment: Environment, ctx: SourceContext):
         repo_name = environment.repository_name
         repo_node_id = environment.repository_node_id
         env_name = environment.name
+        encoded_env_name = _encode_path_segment(env_name)
         env_node_id = environment.node_id
         client = _client_for_org(ctx, environment.org_login)
         for page in client.paginate(
-            f"/repos/{full_repo_name}/environments/{env_name}/deployment-branch-policies"
+            f"/repos/{full_repo_name}/environments/{encoded_env_name}/deployment-branch-policies"
         ):
             for policy in page:
                 yield {
@@ -1377,10 +1384,11 @@ def environment_secrets(environment: Environment, ctx: SourceContext):
     full_repo_name = environment.repository_full_name
 
     env_name = environment.name
+    encoded_env_name = _encode_path_segment(env_name)
     env_node_id = environment.node_id
     client = _client_for_org(ctx, environment.org_login)
     for page in client.paginate(
-        f"/repos/{full_repo_name}/environments/{env_name}/secrets"
+        f"/repos/{full_repo_name}/environments/{encoded_env_name}/secrets"
     ):
         for secret in page:
             yield {

{openhound_github-0.5.0 → openhound_github-0.5.2}/src/openhound_github/source.py

@@ -18,6 +18,7 @@ from openhound_github.auth import (
     GithubApp,
     GitHubAppInstallationAuth,
     GithubInstallation,
+    resolve_github_app_jwt_issuer,
 )
 from openhound_github.helpers import github_retry_policy
 from openhound_github.main import app
@@ -75,8 +76,8 @@ class GithubCredentials(CredentialsConfiguration):
 
 @configspec
 class GithubEnterpriseAppCredentials(CredentialsConfiguration):
-    client_id: str = None
-    app_id: str = None
+    client_id: str | None = None
+    app_id: str | None = None
     key_path: str = None
     enterprise_name: str = None
     pat_token: str | None = None
@@ -151,6 +152,10 @@ def source(
         return client(BearerTokenAuth(token=token))
 
     if credentials.auth == "enterprise_app":
+        jwt_issuer = resolve_github_app_jwt_issuer(
+            client_id=credentials.client_id,
+            app_id=credentials.app_id,
+        )
         ctx = SourceContext(
             enterprise_name=credentials.enterprise_name,
             collect_enterprise_scim=bool(collect_enterprise_scim),
@@ -165,14 +170,14 @@ def source(
         elif credentials.pat_token:
             ctx.scim_client = ctx.sso_client
         github_app_session = GithubApp(
-            client_id=credentials.client_id,
+            jwt_issuer=jwt_issuer,
             private_key_path=credentials.key_path,
         )
         for installation in github_app_session.installations:
             if installation.target_type == "Organization":
                 org_installation = GithubInstallation(
                     installation_id=installation.id,
-                    client_id=installation.client_id,
+                    jwt_issuer=jwt_issuer,
                     private_key_path=credentials.key_path,
                 )
                 ctx.organizations.append(
@@ -189,7 +194,7 @@ def source(
             if installation.target_type == "Enterprise":
                 es_installation = GithubInstallation(
                     installation_id=installation.id,
-                    client_id=installation.client_id,
+                    jwt_issuer=jwt_issuer,
                     private_key_path=credentials.key_path,
                 )
                 ctx.client = client(
@@ -206,7 +211,7 @@ def source(
         )
         org_installation = GithubInstallation(
             installation_id=credentials.install_id,
-            client_id=credentials.client_id,
+            jwt_issuer=credentials.client_id,
             private_key_path=credentials.key_path,
         )
         ctx.organizations.append(

openhound_github-0.5.2/tests/test_app_auth.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import importlib
+from types import SimpleNamespace
+
+import pytest
+from dlt.common.configuration.resolve import resolve_configuration
+
+from openhound_github import auth
+from openhound_github.auth import (
+    AccountConfig,
+    GithubSession,
+    InstallationResponse,
+    resolve_github_app_jwt_issuer,
+)
+from openhound_github.source import GithubEnterpriseAppCredentials
+
+
+@pytest.mark.parametrize(
+    ("client_id", "app_id", "expected"),
+    (
+        ("Iv1.client-id", None, "Iv1.client-id"),
+        (None, "123456", "123456"),
+        ("Iv1.preferred", "123456", "Iv1.preferred"),
+        (" Iv1.trimmed ", "123456", "Iv1.trimmed"),
+    ),
+)
+def test_resolve_github_app_jwt_issuer_prefers_client_id(
+    client_id: str | None,
+    app_id: str | None,
+    expected: str,
+) -> None:
+    assert resolve_github_app_jwt_issuer(client_id=client_id, app_id=app_id) == expected
+
+
+def test_resolve_github_app_jwt_issuer_requires_an_identifier() -> None:
+    with pytest.raises(
+        ValueError,
+        match="require either client_id or app_id for the JWT issuer",
+    ):
+        resolve_github_app_jwt_issuer(client_id=None, app_id=None)
+
+
+@pytest.mark.parametrize(
+    ("client_id", "app_id"),
+    (("Iv1.client-id", None), (None, "123456")),
+)
+def test_enterprise_app_configuration_accepts_either_identifier(
+    client_id: str | None,
+    app_id: str | None,
+) -> None:
+    credentials = resolve_configuration(
+        GithubEnterpriseAppCredentials(
+            client_id=client_id,
+            app_id=app_id,
+            key_path="/tmp/github-app.pem",
+            enterprise_name="example-enterprise",
+        )
+    )
+
+    assert credentials.is_partial() is False
+
+
+def test_github_session_uses_explicit_jwt_issuer(
+    monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+    key_path = tmp_path / "github-app.pem"
+    key_path.write_text("test-private-key", encoding="utf-8")
+    captured_claims: dict[str, object] = {}
+
+    monkeypatch.setattr(auth.RSAKey, "import_key", lambda _: object())
+
+    def fake_encode(header, claims, key):
+        captured_claims.update(claims)
+        return "encoded-jwt"
+
+    monkeypatch.setattr(auth.jwt, "encode", fake_encode)
+
+    session = GithubSession(
+        jwt_issuer="123456",
+        private_key_path=str(key_path),
+    )
+
+    assert session.jwt == "encoded-jwt"
+    assert captured_claims["iss"] == "123456"
+
+
+def test_legacy_installation_response_does_not_require_client_id() -> None:
+    installation = InstallationResponse(
+        id=42,
+        account=AccountConfig(id=7, login="example-org"),
+        target_type="Organization",
+        app_id=123456,
+    )
+
+    assert installation.client_id is None
+    assert installation.app_id == 123456
+
+
+def test_enterprise_source_reuses_selected_issuer_for_installation_tokens(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    source_module = importlib.import_module("openhound_github.source")
+    captured_issuers: list[str] = []
+
+    class FakeGithubApp:
+        def __init__(self, jwt_issuer: str, private_key_path: str) -> None:
+            captured_issuers.append(jwt_issuer)
+            self.installations = (
+                SimpleNamespace(
+                    id=11,
+                    target_type="Organization",
+                    account=SimpleNamespace(login="example-org"),
+                ),
+                SimpleNamespace(
+                    id=12,
+                    target_type="Enterprise",
+                    account=SimpleNamespace(slug="example-enterprise"),
+                ),
+            )
+
+    class FakeGithubInstallation:
+        def __init__(
+            self,
+            installation_id: int,
+            jwt_issuer: str,
+            private_key_path: str,
+        ) -> None:
+            captured_issuers.append(jwt_issuer)
+
+    class FakeRESTClient:
+        def __init__(self, **kwargs) -> None:
+            pass
+
+    monkeypatch.setattr(source_module, "GithubApp", FakeGithubApp)
+    monkeypatch.setattr(source_module, "GithubInstallation", FakeGithubInstallation)
+    monkeypatch.setattr(
+        source_module, "GitHubAppInstallationAuth", lambda **_: object()
+    )
+    monkeypatch.setattr(source_module, "RESTClient", FakeRESTClient)
+    monkeypatch.setattr(source_module, "enterprise_resources", lambda _: ())
+    monkeypatch.setattr(source_module, "organization_resources", lambda _: ())
+
+    resources = source_module.source.__wrapped__(
+        credentials=GithubEnterpriseAppCredentials(
+            app_id="123456",
+            key_path="/tmp/github-app.pem",
+            enterprise_name="example-enterprise",
+        ),
+        host="https://api.github.com",
+        collect_enterprise_scim=False,
+        emit_legacy_scim_correlations=False,
+    )
+
+    assert resources == ()
+    assert captured_issuers == ["123456", "123456", "123456"]

openhound_github-0.5.2/tests/test_environment_resources.py

@@ -0,0 +1,73 @@
+from types import SimpleNamespace
+
+import pytest
+
+from openhound_github.resources.organization import (
+    OrgContext,
+    SourceContext,
+    environment_branch_policies,
+    environment_secrets,
+    environment_variables,
+)
+
+
+class _FakeClient:
+    def __init__(self):
+        self.paginate_calls: list[tuple[str, dict]] = []
+
+    def paginate(self, path: str, **kwargs):
+        self.paginate_calls.append((path, kwargs))
+        return iter([])
+
+
+def _ctx(client: _FakeClient) -> SourceContext:
+    return SourceContext(
+        client=client,
+        organizations=[OrgContext(client=client, org_name="acme")],
+    )
+
+
+def _environment(name: str) -> SimpleNamespace:
+    return SimpleNamespace(
+        name=name,
+        node_id="ENV_1",
+        org_login="acme",
+        repository_name="repo",
+        repository_full_name="acme/repo",
+        repository_node_id="REPO_1",
+        has_custom_branch_policies=True,
+        required_reviewers=False,
+        prevent_self_review=False,
+    )
+
+
+@pytest.mark.parametrize(
+    ("transformer", "suffix"),
+    [
+        (environment_variables, "variables"),
+        (environment_secrets, "secrets"),
+        (environment_branch_policies, "deployment-branch-policies"),
+    ],
+)
+@pytest.mark.parametrize(
+    ("environment_name", "encoded_name"),
+    [
+        ("feature/test", "feature%2Ftest"),
+        ("QA Environment", "QA%20Environment"),
+        (
+            "PCF_PROD_Deployment / deploy-PROD",
+            "PCF_PROD_Deployment%20%2F%20deploy-PROD",
+        ),
+    ],
+)
+def test_environment_child_resources_encode_environment_names_in_paths(
+    transformer, suffix: str, environment_name: str, encoded_name: str
+) -> None:
+    client = _FakeClient()
+
+    rows = list(transformer.__wrapped__(_environment(environment_name), _ctx(client)))
+
+    assert rows == []
+    assert client.paginate_calls == [
+        (f"/repos/acme/repo/environments/{encoded_name}/{suffix}", {})
+    ]