openhound-github 0.10.0__tar.gz → 0.10.1__tar.gz

{openhound_github-0.10.0 → openhound_github-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhound-github
-Version: 0.10.0
+Version: 0.10.1
 Summary: Github collector for OpenHound
 Author-email: "jdreijer@specterops.io" <jdreijer@specterops.io>, Jared Atkinson <jatkinson@specterops.io>
 License-File: LICENSE.md

openhound_github-0.10.1/descriptions/edges/GH_CanRequestOIDCTokenFor.md

@@ -0,0 +1,26 @@
+# GH_CanRequestOIDCTokenFor
+
+## General Information
+
+The traversable GH_CanRequestOIDCTokenFor edge represents a static upper-bound capability: based on the collected workflow configuration, a GitHub Actions workflow job execution context may be able to request a GitHub-signed OIDC token containing claims for its associated GitHub Environment.
+
+This edge is derived from the existing GH_DeploysTo relationship and the job's calculated `effective_github_token_permissions`. The collector emits it only when the job targets a statically resolved environment and its effective permissions include `id-token:write`.
+
+This is a capability edge, not evidence that the workflow has historically requested a token or contains an explicit OIDC-related step. Code executing in a job with `id-token:write` can request the token directly.
+
+The edge does not model run-specific permission recalculation. In particular, a `pull_request` run originating from a fork may receive downgraded `GITHUB_TOKEN` permissions at runtime and therefore may not be able to request an OIDC token even when this edge exists. The edge should not be interpreted as proof that every execution of the job can request OIDC.
+
+## Edge Schema
+
+| Source | Destination | Traversable |
+| --- | --- | --- |
+| `GH_WorkflowJob` | `GH_Environment` | `true` |
+
+## Diagram
+
+```mermaid
+graph LR
+    n0["GH_WorkflowJob"]
+    n1["GH_Environment"]
+    n0 -->|GH_CanRequestOIDCTokenFor| n1
+```

{openhound_github-0.10.0 → openhound_github-0.10.1}/descriptions/nodes/GH_Environment.md

@@ -6,6 +6,8 @@ Represents a GitHub Actions deployment environment configured on a repository. E
 
 Repositories always contain their environments. When custom branch policies are configured, the environment also contains one or more GH_EnvironmentBranchPolicy nodes that describe which branches are allowed to deploy. Environment-scoped secrets and variables are modeled as child nodes of the environment and become available to workflow jobs that reference it.
 
+GH_CanRequestOIDCTokenFor edges from GH_WorkflowJob nodes identify jobs with a static upper-bound capability to request a GitHub-signed OIDC token for this environment because their effective `GITHUB_TOKEN` permissions include `id-token:write`. Runtime permission recalculation, such as forked `pull_request` permission downgrades, may prevent a specific execution from requesting OIDC even when this edge exists.
+
 ## Properties
 
 | Property | Type | Description |
@@ -57,4 +59,5 @@ graph LR
     n8 -.->|GH_ApprovesDeploymentTo| n1
     n8 -->|GH_CanDeployToEnvironment| n1
     n9 -.->|GH_DeploysTo| n1
+    n9 -->|GH_CanRequestOIDCTokenFor| n1
 ```

{openhound_github-0.10.0 → openhound_github-0.10.1}/descriptions/nodes/GH_WorkflowJob.md

@@ -8,7 +8,7 @@ When the job has a statically resolvable self-hosted `runs-on` selector, GH_Runs
 
 When present, `job_permissions` captures the job-level `permissions` declaration from the workflow YAML. `effective_github_token_permissions` captures the calculated static `GITHUB_TOKEN` permissions after applying the repository default, workflow-level declaration, and job-level declaration.
 
-GH_CanAccessSecret edges identify secrets statically referenced by the job's modeled steps or job-level `env` block that the job execution context can access. GH_CanInterceptJob edges from GH_Runner nodes not explicitly marked ephemeral identify jobs whose future execution context may be exposed if that runner is controlled.
+GH_CanAccessSecret edges identify secrets statically referenced by the job's modeled steps or job-level `env` block that the job execution context can access. GH_CanInterceptJob edges from GH_Runner nodes not explicitly marked ephemeral identify jobs whose future execution context may be exposed if that runner is controlled. When a job targets an environment and its effective permissions include `id-token:write`, GH_CanRequestOIDCTokenFor identifies a static upper-bound OIDC capability for that environment. Runtime permission recalculation, such as forked `pull_request` permission downgrades, may prevent a specific execution from requesting OIDC even when this edge exists.
 
 When `runs_on_is_dynamic` is true, runner matching and interception status remain unresolved: the collector does not emit GH_CanInterceptJob edges for the job, so `query_interceptable_jobs` cannot match it and the absence of an edge must not be treated as evidence that the job is definitively non-interceptable.
 
@@ -70,6 +70,7 @@ graph LR
     n1 -->|GH_CanAccessSecret| n3
     n1 -->|GH_CanAccessSecret| n5
     n1 -->|GH_CanAccessSecret| n7
+    n1 -->|GH_CanRequestOIDCTokenFor| n2
     n9 -->|GH_CanInterceptJob| n1
     n1 -.->|GH_CallsWorkflow| n0
     n1 -.->|GH_DependsOn| n1

{openhound_github-0.10.0 → openhound_github-0.10.1}/extension/schema.json

@@ -1055,6 +1055,11 @@
       "description": "[Computed] Workflow job execution context can access a statically referenced secret — GH_WorkflowJob → GH_RepoSecret / GH_OrgSecret / GH_EnvironmentSecret",
       "is_traversable": true
     },
+    {
+      "name": "GH_CanRequestOIDCTokenFor",
+      "description": "[Computed] Workflow job has a static upper-bound capability to request a GitHub OIDC token for its deployment environment — GH_WorkflowJob → GH_Environment",
+      "is_traversable": true
+    },
     {
       "name": "GH_UsesVariable",
       "description": "[Workflow] Job or step references a variable by name — GH_WorkflowJob / GH_WorkflowStep → GH_RepoVariable / GH_OrgVariable / GH_EnvironmentVariable (scope match)",

{openhound_github-0.10.0 → openhound_github-0.10.1}/src/openhound_github/kinds/edges.py

@@ -20,7 +20,8 @@ CAN_ACCESS = "GH_CanAccess"
 CAN_USE_RUNNER = "GH_CanUseRunner"
 RUNS_ON = "GH_RunsOn"
 CAN_INTERCEPT_JOB = "GH_CanInterceptJob"
-CAN_ACCESS_SECRET = "GH_CanAccessSecret"
+CAN_ACCESS_SECRET = "GH_CanAccessSecret"  # noqa: S105 - OpenGraph edge kind
+CAN_REQUEST_OIDC_TOKEN_FOR = "GH_CanRequestOIDCTokenFor"  # noqa: S105 - OpenGraph edge kind
 IS_ELIGIBLE_FOR = "GH_IsEligibleFor"
 CAN_CREATE_REPOSITORY_WITH_RUNNER_ACCESS = "GH_CanCreateRepositoryWithRunnerAccess"
 CAN_CREATE_BRANCH = "GH_CanCreateBranch"

{openhound_github-0.10.0 → openhound_github-0.10.1}/src/openhound_github/lookup.py

@@ -243,18 +243,21 @@ class GithubLookup(LookupManager):
 
         repository_visibility, actions_enabled = repository
         required_labels = {str(label).casefold() for label in labels}
-        matching_runners: list[tuple[str, bool | None]] = []
+        matching_runners: list[tuple[int, str, bool | None]] = []
         seen_runner_node_ids: set[str] = set()
 
         def add_matching_runner(
-            node_id: str, raw_labels: Any, ephemeral: bool | None
+            source_order: int,
+            node_id: str,
+            raw_labels: Any,
+            ephemeral: bool | None,
         ) -> None:
             if node_id in seen_runner_node_ids:
                 return
             if not required_labels.issubset(self._runner_label_names(raw_labels)):
                 return
             seen_runner_node_ids.add(node_id)
-            matching_runners.append((node_id, ephemeral))
+            matching_runners.append((source_order, node_id, ephemeral))
 
         if group_name is None:
             for runner_id, raw_labels, ephemeral in self._find_all_objects(
@@ -266,6 +269,7 @@ class GithubLookup(LookupManager):
                 [repository_node_id],
             ):
                 add_matching_runner(
+                    0,
                     runner_node_id(repository_node_id, int(runner_id)),
                     raw_labels,
                     ephemeral,
@@ -345,6 +349,7 @@ class GithubLookup(LookupManager):
                     [enterprise_node_id, enterprise_runner_group_id],
                 ):
                     add_matching_runner(
+                        2,
                         runner_node_id(enterprise_node_id, int(runner_id)),
                         raw_labels,
                         ephemeral,
@@ -364,12 +369,19 @@ class GithubLookup(LookupManager):
                 [org_login, runner_group_id],
             ):
                 add_matching_runner(
+                    1,
                     runner_node_id(self.org_id_for_login(org_login), int(runner_id)),
                     raw_labels,
                     ephemeral,
                 )
 
-        return matching_runners
+        return [
+            (node_id, ephemeral)
+            for _source_order, node_id, ephemeral in sorted(
+                matching_runners,
+                key=lambda runner: (runner[0], runner[1]),
+            )
+        ]
 
     @lru_cache
     def workflow_job_runner_node_ids(
@@ -594,6 +606,9 @@ class GithubLookup(LookupManager):
                 repository_can_approve_pull_request_reviews
             FROM {self.schema}.workflows
             WHERE repository_node_id = ?
+            ORDER BY
+                repository_default_workflow_permissions IS NULL,
+                repository_can_approve_pull_request_reviews IS NULL
             LIMIT 1
             """,
             [repository_node_id],

{openhound_github-0.10.0 → openhound_github-0.10.1}/src/openhound_github/models/workflow_job.py

@@ -198,6 +198,13 @@ class GHWorkflowJobProperties(GHNodeProperties):
             description="Workflow job execution context can access environment secret",
             traversable=True,
         ),
+        EdgeDef(
+            start=nk.WORKFLOW_JOB,
+            end=nk.ENVIRONMENT,
+            kind=ek.CAN_REQUEST_OIDC_TOKEN_FOR,
+            description="Workflow job has a static upper-bound capability to request an OIDC token for environment",
+            traversable=True,
+        ),
     ],
 )
 class WorkflowJob(BaseAsset):
@@ -419,7 +426,10 @@ class WorkflowJob(BaseAsset):
     @property
     def _environment_edges(self):
         if self.environment and not TEMPLATE_RE.search(self.environment):
-            if self._lookup.environment(self.environment, self.repository_node_id):
+            persisted_environment_name = self._lookup.environment(
+                self.environment, self.repository_node_id
+            )
+            if persisted_environment_name:
                 yield Edge(
                     kind=ek.DEPLOYS_TO,
                     start=EdgePath(value=self.node_id, match_by="id"),
@@ -429,12 +439,39 @@ class WorkflowJob(BaseAsset):
                             PropertyMatch(
                                 key="repository_id", value=self.repository_node_id
                             ),
-                            PropertyMatch(key="name", value=self.environment.upper()),
+                            PropertyMatch(key="name", value=persisted_environment_name),
                         ],
                     ),
                     properties=EdgeProperties(traversable=False),
                 )
 
+    def _can_request_oidc_token_for_query(self) -> str:
+        return (
+            f"MATCH p=(job:GH_WorkflowJob {{node_id:'{self.node_id}'}})"
+            "-[:GH_DeploysTo]->(:GH_Environment) "
+            "WHERE 'id-token:write' IN job.effective_github_token_permissions "
+            "RETURN p"
+        )
+
+    @property
+    def _can_request_oidc_token_for_edges(self):
+        if "id-token:write" not in (
+            self.calculated_effective_github_token_permissions or []
+        ):
+            return
+
+        for environment_edge in self._environment_edges:
+            yield Edge(
+                kind=ek.CAN_REQUEST_OIDC_TOKEN_FOR,
+                start=environment_edge.start,
+                end=environment_edge.end,
+                properties=GHEdgeProperties(
+                    traversable=True,
+                    composed=True,
+                    query_composition=self._can_request_oidc_token_for_query(),
+                ),
+            )
+
     @property
     def _calls_workflows_edge(self):
         if self.uses_reusable and self.uses_reusable.startswith("./.github/workflows/"):
@@ -573,3 +610,4 @@ class WorkflowJob(BaseAsset):
         yield from self._runs_on_edges
         yield from self._can_intercept_job_edges
         yield from self._can_access_secret_edges
+        yield from self._can_request_oidc_token_for_edges

{openhound_github-0.10.0 → openhound_github-0.10.1}/tests/test_repository_rulesets.py

@@ -443,7 +443,8 @@ def test_repository_workflow_permissions_lookup_returns_collected_policy() -> No
         "CREATE TABLE github.workflows (repository_node_id VARCHAR, repository_default_workflow_permissions VARCHAR, repository_can_approve_pull_request_reviews BOOLEAN)"
     )
     connection.execute(
-        "INSERT INTO github.workflows VALUES ('R_1', 'read', false), ('R_2', NULL, NULL)"
+        "INSERT INTO github.workflows VALUES "
+        "('R_1', NULL, NULL), ('R_1', 'read', false), ('R_2', NULL, NULL)"
     )
 
     lookup = GithubLookup(connection)

{openhound_github-0.10.0 → openhound_github-0.10.1}/tests/test_runner_models.py

@@ -65,9 +65,9 @@ def _workflow_runner_lookup() -> GithubLookup:
     )
     connection.execute(
         """INSERT INTO github.org_runners VALUES
-        (11, '[{"name":"self-hosted"},{"name":"Linux"},{"name":"X64"}]', false, 'acme'),
         (12, '[{"name":"self-hosted"},{"name":"Linux"},{"name":"ARM64"}]', true, 'acme'),
-        (13, '[{"name":"self-hosted"},{"name":"Windows"},{"name":"X64"}]', NULL, 'acme')"""
+        (13, '[{"name":"self-hosted"},{"name":"Windows"},{"name":"X64"}]', NULL, 'acme'),
+        (11, '[{"name":"self-hosted"},{"name":"Linux"},{"name":"X64"}]', false, 'acme')"""
     )
     connection.execute(
         """INSERT INTO github.org_runner_group_access VALUES
@@ -77,7 +77,7 @@ def _workflow_runner_lookup() -> GithubLookup:
         (4, 'enterprise-prod', 'selected', true, false, true, '["REPO_1"]', 'acme')"""
     )
     connection.execute(
-        "INSERT INTO github.org_runner_group_memberships VALUES (1, 11, 'acme'), (1, 12, 'acme'), (1, 13, 'acme'), (2, 11, 'acme'), (2, 12, 'acme'), (3, 11, 'acme')"
+        "INSERT INTO github.org_runner_group_memberships VALUES (1, 13, 'acme'), (1, 12, 'acme'), (1, 11, 'acme'), (2, 12, 'acme'), (2, 11, 'acme'), (3, 11, 'acme')"
     )
     connection.execute(
         "INSERT INTO github.enterprise_organizations VALUES ('ORG_1', 'ENT_1')"

{openhound_github-0.10.0 → openhound_github-0.10.1}/tests/test_workflow_interception_path.py

@@ -81,6 +81,10 @@ def _cross_org_enterprise_runner_lookup() -> GithubLookup:
         "CREATE TABLE github.environment_secrets "
         "(name VARCHAR, repository_node_id VARCHAR, environment_name VARCHAR)"
     )
+    connection.execute(
+        "CREATE TABLE github.environments "
+        "(name VARCHAR, repository_node_id VARCHAR)"
+    )
     connection.execute(
         "INSERT INTO github.organizations VALUES "
         "('attacker', 'ORG_A'), ('victim', 'ORG_B')"
@@ -122,6 +126,9 @@ def _cross_org_enterprise_runner_lookup() -> GithubLookup:
     connection.execute(
         "INSERT INTO github.repository_secrets VALUES ('DEPLOY_TOKEN', 'REPO_B')"
     )
+    connection.execute(
+        "INSERT INTO github.environments VALUES ('prod', 'REPO_B')"
+    )
     return GithubLookup(connection)
 
 
@@ -171,6 +178,8 @@ def test_cross_org_enterprise_runner_interception_path_is_traversable() -> None:
         repository_node_id="REPO_B",
         org_login="victim",
         runs_on={"group": "enterprise-prod", "labels": ["self-hosted", "linux"]},
+        environment="prod",
+        permissions={"id-token": "write"},
     )
     victim_job._lookup = lookup
     victim_step = WorkflowStep(
@@ -209,15 +218,27 @@ def test_cross_org_enterprise_runner_interception_path_is_traversable() -> None:
     can_intercept = _find_edge(
         job_edges, ek.CAN_INTERCEPT_JOB, "ENT_1_runner_31", "JOB_B"
     )
+    deploys_to = _find_edge(job_edges, ek.DEPLOYS_TO, "JOB_B")
     contains_step = _find_edge(job_edges + step_edges, ek.CONTAINS, "JOB_B", "STEP_B")
     uses_secret = _find_edge(step_edges, ek.USES_SECRET, "STEP_B")
     can_access_secret = _find_edge(job_edges, ek.CAN_ACCESS_SECRET, "JOB_B")
+    can_request_oidc_token = _find_edge(
+        job_edges, ek.CAN_REQUEST_OIDC_TOKEN_FOR, "JOB_B"
+    )
 
     assert [
         edge.properties.traversable
-        for edge in [can_use, inherited_from, has_runner, can_intercept, can_access_secret]
-    ] == [True, True, True, True, True]
+        for edge in [
+            can_use,
+            inherited_from,
+            has_runner,
+            can_intercept,
+            can_access_secret,
+            can_request_oidc_token,
+        ]
+    ] == [True, True, True, True, True, True]
     assert runs_on.properties.traversable is False
+    assert deploys_to.properties.traversable is False
     assert contains_step.properties.traversable is False
     assert uses_secret.properties.traversable is False
     assert uses_secret.end.kind == nk.REPO_SECRET
@@ -229,6 +250,20 @@ def test_cross_org_enterprise_runner_interception_path_is_traversable() -> None:
         "name": "DEPLOY_TOKEN",
         "repository_id": "REPO_B",
     }
+    assert can_request_oidc_token.end.kind == nk.ENVIRONMENT
+    assert {
+        matcher.key: matcher.value
+        for matcher in can_request_oidc_token.end.property_matchers
+    } == {
+        "name": "prod",
+        "repository_id": "REPO_B",
+    }
+    assert {
+        matcher.key: matcher.value for matcher in deploys_to.end.property_matchers
+    } == {
+        "name": "prod",
+        "repository_id": "REPO_B",
+    }
 
 
 def test_inherited_runner_lookup_survives_upgraded_enterprise_runner_group_stub() -> None:

{openhound_github-0.10.0 → openhound_github-0.10.1}/tests/test_workflow_model.py

@@ -476,6 +476,134 @@ def test_workflow_job_emits_can_access_secret_edges_for_step_references() -> Non
     assert "GH_UsesSecret" in edges[0].properties.query_composition
 
 
+def test_workflow_job_emits_can_request_oidc_token_for_environment_without_oidc_step() -> None:
+    job = WorkflowJob(
+        node_id="JOB_1",
+        name="deploy",
+        job_key="deploy",
+        workflow_node_id="WORKFLOW_1",
+        repository_name="repo",
+        repository_node_id="REPO_1",
+        org_login="github",
+        environment="prod",
+        permissions={"id-token": "write"},
+    )
+    lookup = _org_reference_lookup()
+    lookup.environment.return_value = "prod"
+    job._lookup = lookup
+
+    environment_edges = list(job._environment_edges)
+    edges = list(job._can_request_oidc_token_for_edges)
+
+    assert len(environment_edges) == 1
+    assert _matcher_values(environment_edges[0]) == {
+        "repository_id": "REPO_1",
+        "name": "prod",
+    }
+    assert len(edges) == 1
+    assert edges[0].kind == ek.CAN_REQUEST_OIDC_TOKEN_FOR
+    assert edges[0].start.value == "JOB_1"
+    assert edges[0].end.kind == nk.ENVIRONMENT
+    assert _matcher_values(edges[0]) == {
+        "repository_id": "REPO_1",
+        "name": "prod",
+    }
+    assert edges[0].properties.traversable is True
+    assert edges[0].properties.composed is True
+    assert edges[0].properties.query_composition == (
+        "MATCH p=(job:GH_WorkflowJob {node_id:'JOB_1'})"
+        "-[:GH_DeploysTo]->(:GH_Environment) "
+        "WHERE 'id-token:write' IN job.effective_github_token_permissions "
+        "RETURN p"
+    )
+
+
+def test_workflow_job_can_request_oidc_token_for_requires_permission_and_environment() -> None:
+    no_permission = WorkflowJob(
+        node_id="JOB_NO_PERMISSION",
+        name="deploy",
+        job_key="deploy",
+        workflow_node_id="WORKFLOW_1",
+        repository_name="repo",
+        repository_node_id="REPO_1",
+        org_login="github",
+        environment="prod",
+        permissions={"contents": "read"},
+    )
+    no_environment = WorkflowJob(
+        node_id="JOB_NO_ENVIRONMENT",
+        name="deploy",
+        job_key="deploy",
+        workflow_node_id="WORKFLOW_1",
+        repository_name="repo",
+        repository_node_id="REPO_1",
+        org_login="github",
+        permissions={"id-token": "write"},
+    )
+    lookup = _org_reference_lookup()
+    lookup.environment.return_value = "prod"
+    no_permission._lookup = lookup
+    no_environment._lookup = lookup
+
+    assert list(no_permission._can_request_oidc_token_for_edges) == []
+    assert list(no_environment._can_request_oidc_token_for_edges) == []
+
+
+def test_workflow_job_can_request_oidc_token_for_edges_are_per_job_and_idempotent() -> None:
+    jobs = [
+        WorkflowJob(
+            node_id="JOB_1",
+            name="deploy",
+            job_key="deploy",
+            workflow_node_id="WORKFLOW_1",
+            repository_name="repo",
+            repository_node_id="REPO_1",
+            org_login="github",
+            environment="prod",
+            permissions={"id-token": "write"},
+        ),
+        WorkflowJob(
+            node_id="JOB_2",
+            name="publish",
+            job_key="publish",
+            workflow_node_id="WORKFLOW_1",
+            repository_name="repo",
+            repository_node_id="REPO_1",
+            org_login="github",
+            environment="prod",
+            permissions={"id-token": "write"},
+        ),
+        WorkflowJob(
+            node_id="JOB_3",
+            name="build",
+            job_key="build",
+            workflow_node_id="WORKFLOW_1",
+            repository_name="repo",
+            repository_node_id="REPO_1",
+            org_login="github",
+            environment="prod",
+            permissions={"contents": "read"},
+        ),
+    ]
+    lookup = _org_reference_lookup()
+    lookup.environment.return_value = "prod"
+    for job in jobs:
+        job._lookup = lookup
+
+    edges = [
+        edge
+        for job in jobs
+        for edge in job.edges
+        if edge.kind == ek.CAN_REQUEST_OIDC_TOKEN_FOR
+    ]
+
+    assert [(edge.start.value, _matcher_values(edge)) for edge in edges] == [
+        ("JOB_1", {"repository_id": "REPO_1", "name": "prod"}),
+        ("JOB_2", {"repository_id": "REPO_1", "name": "prod"}),
+    ]
+    assert len(list(jobs[0]._can_request_oidc_token_for_edges)) == 1
+
+
 def test_workflow_job_can_access_secret_edges_deduplicate_step_references() -> None:
     job = WorkflowJob(
         node_id="JOB_1",
@@ -592,6 +720,7 @@ def _org_reference_lookup() -> MagicMock:
     lookup = MagicMock()
     lookup.org_id_for_login.return_value = ORG_NODE_ID
     lookup.repository_workflow_permissions.return_value = None
+    lookup.environment.return_value = None
     lookup.workflow_step_secret_reference_names.return_value = []
     lookup.repo_secret.return_value = None
     lookup.org_secret.return_value = ("DEPLOY_TOKEN",)