openhound-github 0.7.3__tar.gz → 0.8.0__tar.gz

{openhound_github-0.7.3 → openhound_github-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhound-github
-Version: 0.7.3
+Version: 0.8.0
 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.8.0/descriptions/edges/GH_RunsOn.md

@@ -0,0 +1,24 @@
+# GH_RunsOn
+
+## General Information
+
+The non-traversable GH_RunsOn edge represents that a GitHub Actions workflow job can be scheduled on a self-hosted runner based on the job's statically declared `runs-on` selector and the runner topology visible to the containing repository.
+
+This edge is schedulability evidence, not historical execution evidence. It does not mean that the job has previously executed on the runner. It means that the runner satisfies the job's static label and runner-group requirements and is reachable through the repository's current runner access policy.
+
+The collector emits GH_RunsOn only for static selectors. Dynamic selectors that contain GitHub Actions expressions such as `${{ matrix.runner }}` or `${{ inputs.runner }}` are intentionally left unresolved in this first implementation.
+
+## Edge Schema
+
+| Source | Destination | Traversable |
+| --- | --- | --- |
+| `GH_WorkflowJob` | `GH_Runner` | `false` |
+
+## Diagram
+
+```mermaid
+graph LR
+    n0["GH_WorkflowJob"]
+    n1["GH_Runner"]
+    n0 -.->|GH_RunsOn| n1
+```

{openhound_github-0.7.3 → openhound_github-0.8.0}/descriptions/nodes/GH_EnterpriseRunner.md

@@ -6,6 +6,8 @@ Represents a self-hosted runner owned at the GitHub Enterprise level. Enterprise
 
 The node captures runner metadata such as operating system, status, busy state, labels, and whether the runner is ephemeral when GitHub returns that property.
 
+GH_RunsOn edges from GH_WorkflowJob nodes identify statically resolvable jobs that GitHub could schedule on this runner through the inherited enterprise runner-group topology. These edges do not indicate that the job has actually executed on the runner.
+
 ## Properties
 
 | Property | Type | Description |
@@ -31,6 +33,7 @@ The node captures runner metadata such as operating system, status, busy state,
 | `environment_name` | `string` | The name of the environment (GitHub organization). |
 | `query_group` | `string` | Query for group. |
 | `query_repositories` | `string` | Query for repositories. |
+| `query_jobs` | `string` | Query for workflow jobs that can be scheduled on the runner. |
 
 ## Diagram
 
@@ -38,6 +41,8 @@ The node captures runner metadata such as operating system, status, busy state,
 graph LR
     n0["GH_EnterpriseRunnerGroup"]
     n1["GH_EnterpriseRunner"]
+    n2["GH_WorkflowJob"]
     n0 -.->|GH_Contains| n1
     n0 -->|GH_HasRunner| n1
+    n2 -.->|GH_RunsOn| n1
 ```

{openhound_github-0.7.3 → openhound_github-0.8.0}/descriptions/nodes/GH_OrgRunner.md

@@ -6,6 +6,8 @@ Represents a self-hosted runner owned by a GitHub organization. Organization run
 
 The node captures runner metadata such as operating system, status, busy state, labels, and whether the runner is ephemeral when GitHub returns that property.
 
+GH_RunsOn edges from GH_WorkflowJob nodes identify statically resolvable jobs that GitHub could schedule on this runner under the current runner-group access policy. These edges do not indicate that the job has actually executed on the runner.
+
 ## Properties
 
 | Property | Type | Description |
@@ -31,6 +33,7 @@ The node captures runner metadata such as operating system, status, busy state,
 | `environment_name` | `string` | The name of the environment (GitHub organization). |
 | `query_group` | `string` | Query for group. |
 | `query_repositories` | `string` | Query for repositories. |
+| `query_jobs` | `string` | Query for workflow jobs that can be scheduled on the runner. |
 
 ## Diagram
 
@@ -38,6 +41,8 @@ The node captures runner metadata such as operating system, status, busy state,
 graph LR
     n0["GH_OrgRunnerGroup"]
     n1["GH_OrgRunner"]
+    n2["GH_WorkflowJob"]
     n0 -.->|GH_Contains| n1
     n0 -->|GH_HasRunner| n1
+    n2 -.->|GH_RunsOn| n1
 ```

{openhound_github-0.7.3 → openhound_github-0.8.0}/descriptions/nodes/GH_RepoRunner.md

@@ -6,6 +6,8 @@ Represents a self-hosted runner registered directly to a single GitHub repositor
 
 The node captures runner metadata such as operating system, status, busy state, labels, and whether the runner is ephemeral when GitHub returns that property.
 
+GH_RunsOn edges from GH_WorkflowJob nodes identify statically resolvable jobs in the containing repository that GitHub could schedule on this runner. These edges do not indicate that the job has actually executed on the runner.
+
 ## Properties
 
 | Property | Type | Description |
@@ -31,6 +33,7 @@ The node captures runner metadata such as operating system, status, busy state,
 | `environment_name` | `string` | The name of the environment (GitHub organization). |
 | `query_group` | `string` | Query for group. |
 | `query_repositories` | `string` | Query for repositories. |
+| `query_jobs` | `string` | Query for workflow jobs that can be scheduled on the runner. |
 
 ## Diagram
 
@@ -38,6 +41,8 @@ The node captures runner metadata such as operating system, status, busy state,
 graph LR
     n0["GH_Repository"]
     n1["GH_RepoRunner"]
+    n2["GH_WorkflowJob"]
     n0 -.->|GH_CanUseRunner| n1
     n0 -.->|GH_Contains| n1
+    n2 -.->|GH_RunsOn| n1
 ```

{openhound_github-0.7.3 → openhound_github-0.8.0}/descriptions/nodes/GH_WorkflowJob.md

@@ -4,6 +4,8 @@
 
 Represents a single job within a GitHub Actions workflow. Jobs are the top-level execution units of a workflow — they run on a runner, hold a set of steps, and can declare permissions, environments, and dependencies on other jobs.
 
+When the job has a statically resolvable self-hosted `runs-on` selector, GH_RunsOn edges identify each GH_Runner that currently satisfies the declared label and runner-group constraints under the repository's runner access policy. These edges represent schedulability, not historical execution.
+
 ## Properties
 
 | Property | Type | Description |
@@ -15,6 +17,9 @@ Represents a single job within a GitHub Actions workflow. Jobs are the top-level
 | `node_id` | `string` | The stable identifier used as the OpenGraph node ID; this is the native GitHub node ID where available. |
 | `job_key` | `string` | The YAML key for the job. |
 | `runs_on` | `list[string]` | The runner label expression for the job. |
+| `runs_on_group` | `string` | The statically declared runner group, if any. |
+| `runs_on_labels` | `list[string]` | The normalized runner labels from runs-on. |
+| `runs_on_is_dynamic` | `boolean` | Whether runs-on contains a GitHub Actions expression. |
 | `is_self_hosted` | `boolean` | Whether the job targets self-hosted runners. |
 | `container` | `string` | The optional container configuration. |
 | `environment` | `string` | The deployment environment name. |
@@ -27,6 +32,7 @@ Represents a single job within a GitHub Actions workflow. Jobs are the top-level
 | `query_repository` | `string` | Query for repository. |
 | `query_steps` | `string` | Query for workflow steps. |
 | `query_references` | `string` | Query for workflow references (secrets and variables). |
+| `query_runners` | `string` | Query for eligible self-hosted runners. |
 
 ## Diagram
 
@@ -41,7 +47,8 @@ graph LR
     n6["GH_OrgVariable"]
     n7["GH_RepoSecret"]
     n8["GH_RepoVariable"]
-    n9["GH_WorkflowStep"]
+    n9["GH_Runner"]
+    n10["GH_WorkflowStep"]
     n0 -.->|GH_Contains| n1
     n1 -.->|GH_DeploysTo| n2
     n1 -.->|GH_UsesSecret| n3
@@ -50,7 +57,8 @@ graph LR
     n1 -.->|GH_UsesVariable| n6
     n1 -.->|GH_UsesSecret| n7
     n1 -.->|GH_UsesVariable| n8
+    n1 -.->|GH_RunsOn| n9
     n1 -.->|GH_CallsWorkflow| n0
     n1 -.->|GH_DependsOn| n1
-    n1 -.->|GH_Contains| n9
+    n1 -.->|GH_Contains| n10
 ```

{openhound_github-0.7.3 → openhound_github-0.8.0}/extension/schema.json

@@ -1030,6 +1030,11 @@
       "description": "[Workflow] Job deploys to a GitHub Environment — GH_WorkflowJob → GH_Environment",
       "is_traversable": false
     },
+    {
+      "name": "GH_RunsOn",
+      "description": "[Workflow] Job can be scheduled on this self-hosted runner based on its static runs-on selector — GH_WorkflowJob → GH_Runner",
+      "is_traversable": false
+    },
     {
       "name": "GH_HasMember",
       "description": "Enterprise or organization has this user as a member",

{openhound_github-0.7.3 → openhound_github-0.8.0}/src/openhound_github/kinds/edges.py

@@ -18,6 +18,7 @@ MEMBER_OF = "GH_MemberOf"
 # Access and capability edges
 CAN_ACCESS = "GH_CanAccess"
 CAN_USE_RUNNER = "GH_CanUseRunner"
+RUNS_ON = "GH_RunsOn"
 IS_ELIGIBLE_FOR = "GH_IsEligibleFor"
 CAN_CREATE_REPOSITORY_WITH_RUNNER_ACCESS = "GH_CanCreateRepositoryWithRunnerAccess"
 CAN_CREATE_BRANCH = "GH_CanCreateBranch"

{openhound_github-0.7.3 → openhound_github-0.8.0}/src/openhound_github/lookup.py

@@ -1,6 +1,7 @@
 import json
 import re
 from functools import lru_cache
+from typing import Any
 
 import duckdb
 from duckdb import DuckDBPyConnection
@@ -167,6 +168,204 @@ class GithubLookup(LookupManager):
         )
         return [(runner_node_id(enterprise_node_id, int(runner_id)),) for (runner_id,) in rows]
 
+    @staticmethod
+    def _json_list(raw_value: Any) -> list[Any]:
+        if raw_value is None:
+            return []
+        if isinstance(raw_value, str):
+            try:
+                raw_value = json.loads(raw_value)
+            except json.JSONDecodeError:
+                return []
+        if isinstance(raw_value, list):
+            return raw_value
+        return []
+
+    @classmethod
+    def _runner_label_names(cls, raw_labels: Any) -> set[str]:
+        names: set[str] = set()
+        for label in cls._json_list(raw_labels):
+            if isinstance(label, dict):
+                name = label.get("name")
+            else:
+                name = label
+            if name is not None:
+                names.add(str(name).casefold())
+        return names
+
+    @staticmethod
+    def _runner_group_allows_repository(
+        *,
+        repository_node_id: str,
+        repository_visibility: str | None,
+        runner_group_visibility: str | None,
+        allows_public_repositories: bool | None,
+        accessible_repo_node_ids: set[str],
+    ) -> bool:
+        if runner_group_visibility == "all":
+            in_scope = True
+        elif runner_group_visibility == "private":
+            in_scope = repository_visibility in {"private", "internal"}
+        else:
+            in_scope = repository_node_id in accessible_repo_node_ids
+
+        if not in_scope:
+            return False
+
+        if allows_public_repositories is False:
+            return repository_visibility in {"private", "internal"}
+
+        return True
+
+    @lru_cache
+    def workflow_job_runner_node_ids(
+        self,
+        repository_node_id: str,
+        org_login: str,
+        group_name: str | None,
+        labels: tuple[str, ...],
+    ) -> list[str]:
+        """Return accessible self-hosted runners matching a static runs-on selector."""
+        if not group_name and not labels:
+            return []
+
+        repository = self._find_single_row(
+            f"""
+            SELECT visibility, actions_enabled
+            FROM {self.schema}.repositories
+            WHERE node_id = ?
+              AND org_login = ?
+            """,
+            [repository_node_id, org_login],
+        )
+        if not repository:
+            return []
+
+        repository_visibility, actions_enabled = repository
+        required_labels = {str(label).casefold() for label in labels}
+        matching_runner_node_ids: list[str] = []
+        seen_runner_node_ids: set[str] = set()
+
+        def add_matching_runner(node_id: str, raw_labels: Any) -> 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_runner_node_ids.append(node_id)
+
+        if group_name is None:
+            for runner_id, raw_labels in self._find_all_objects(
+                f"""
+                SELECT id, labels
+                FROM {self.schema}.repo_runners
+                WHERE repository_node_id = ?
+                """,
+                [repository_node_id],
+            ):
+                add_matching_runner(
+                    runner_node_id(repository_node_id, int(runner_id)),
+                    raw_labels,
+                )
+
+        if actions_enabled is not True:
+            return []
+
+        for (
+            runner_group_id,
+            runner_group_name,
+            runner_group_visibility,
+            allows_public_repositories,
+            restricted_to_workflows,
+            inherited,
+            raw_accessible_repo_node_ids,
+        ) in self._find_all_objects(
+            f"""
+            SELECT
+                runner_group_id,
+                runner_group_name,
+                runner_group_visibility,
+                allows_public_repositories,
+                restricted_to_workflows,
+                inherited,
+                accessible_repo_node_ids
+            FROM {self.schema}.org_runner_group_access
+            WHERE org_login = ?
+            """,
+            [org_login],
+        ):
+            if group_name is not None and runner_group_name != group_name:
+                continue
+            if restricted_to_workflows is not False:
+                continue
+
+            accessible_repo_node_ids = {
+                str(node_id)
+                for node_id in self._json_list(raw_accessible_repo_node_ids)
+            }
+            if not self._runner_group_allows_repository(
+                repository_node_id=repository_node_id,
+                repository_visibility=repository_visibility,
+                runner_group_visibility=runner_group_visibility,
+                allows_public_repositories=allows_public_repositories,
+                accessible_repo_node_ids=accessible_repo_node_ids,
+            ):
+                continue
+
+            if inherited:
+                org_node_id = self.org_id_for_login(org_login)
+                if not org_node_id:
+                    continue
+                if (
+                    self.enterprise_runner_group_restricted_to_workflows_for_inherited_org_group(
+                        org_node_id, runner_group_name
+                    )
+                    is not False
+                ):
+                    continue
+                identity = self._enterprise_runner_group_identity_for_inherited_org_group(
+                    org_node_id, runner_group_name
+                )
+                if not identity:
+                    continue
+                enterprise_node_id, enterprise_runner_group_id = identity
+                for runner_id, raw_labels in self._find_all_objects(
+                    f"""
+                    SELECT r.id, r.labels
+                    FROM {self.schema}.enterprise_runner_group_memberships m
+                    JOIN {self.schema}.enterprise_runners r
+                      ON r.enterprise_node_id = m.enterprise_node_id
+                     AND r.id = m.runner_id
+                    WHERE m.enterprise_node_id = ?
+                      AND m.runner_group_id = ?
+                    """,
+                    [enterprise_node_id, enterprise_runner_group_id],
+                ):
+                    add_matching_runner(
+                        runner_node_id(enterprise_node_id, int(runner_id)),
+                        raw_labels,
+                    )
+                continue
+
+            for runner_id, raw_labels in self._find_all_objects(
+                f"""
+                SELECT r.id, r.labels
+                FROM {self.schema}.org_runner_group_memberships m
+                JOIN {self.schema}.org_runners r
+                  ON r.org_login = m.org_login
+                 AND r.id = m.runner_id
+                WHERE m.org_login = ?
+                  AND m.runner_group_id = ?
+                """,
+                [org_login, runner_group_id],
+            ):
+                add_matching_runner(
+                    runner_node_id(self.org_id_for_login(org_login), int(runner_id)),
+                    raw_labels,
+                )
+
+        return matching_runner_node_ids
+
     @lru_cache
     def enterprise_idp_for_scope(
         self, enterprise_node_id: str

{openhound_github-0.7.3 → openhound_github-0.8.0}/src/openhound_github/main.py

@@ -72,6 +72,12 @@ def preproc(ctx: PreProcContext):
         "enterprise_runner_groups": "enterprise_runner_groups",
         "enterprise_runner_group_organizations": "enterprise_runner_group_organizations",
         "enterprise_runner_group_memberships": "enterprise_runner_group_memberships",
+        "enterprise_runners": "enterprise_runners",
+        "runner_groups": "runner_groups",
+        "org_runners": "org_runners",
+        "org_runner_group_access": "org_runner_group_access",
+        "org_runner_group_memberships": "org_runner_group_memberships",
+        "repo_runners": "repo_runners",
         "org_roles": "org_roles",
         "org_role_members": "org_role_members",
         "org_role_teams": "org_role_teams",

{openhound_github-0.7.3 → openhound_github-0.8.0}/src/openhound_github/models/runner.py

@@ -316,6 +316,7 @@ class GHRunnerProperties(GHNodeProperties):
         environment_name: The name of the environment (GitHub organization).
         query_group: Query for group.
         query_repositories: Query for repositories.
+        query_jobs: Query for workflow jobs that can be scheduled on the runner.
     """
 
     scope: str | None = None
@@ -334,6 +335,7 @@ class GHRunnerProperties(GHNodeProperties):
     environment_name: str | None = None
     query_group: str | None = None
     query_repositories: str | None = None
+    query_jobs: str | None = None
 
 
 @app.asset(
@@ -384,6 +386,7 @@ class OrgRunner(BaseAsset):
                 environmentid=self.org_node_id,
                 query_group=f"MATCH p=(:GH_OrgRunnerGroup)-[:GH_HasRunner]->(:GH_OrgRunner {{node_id:'{rid}'}}) RETURN p",
                 query_repositories=f"MATCH p=(:GH_Repository)-[:GH_CanUseRunner]->(:GH_OrgRunnerGroup)-[:GH_HasRunner]->(:GH_OrgRunner {{node_id:'{rid}'}}) RETURN p",
+                query_jobs=f"MATCH p=(:GH_WorkflowJob)-[:GH_RunsOn]->(:GH_Runner {{node_id:'{rid}'}}) RETURN p",
             ),
         )
 
@@ -437,6 +440,7 @@ class EnterpriseRunner(BaseAsset):
                 environmentid=self.enterprise_node_id,
                 query_group=f"MATCH p=(:GH_EnterpriseRunnerGroup)-[:GH_HasRunner]->(:GH_EnterpriseRunner {{node_id:'{rid}'}}) RETURN p",
                 query_repositories=f"MATCH p=(:GH_Repository)-[:GH_CanUseRunner]->(:GH_OrgRunnerGroup)-[:GH_InheritedFrom]->(:GH_EnterpriseRunnerGroup)-[:GH_HasRunner]->(:GH_EnterpriseRunner {{node_id:'{rid}'}}) RETURN p",
+                query_jobs=f"MATCH p=(:GH_WorkflowJob)-[:GH_RunsOn]->(:GH_Runner {{node_id:'{rid}'}}) RETURN p",
             ),
         )
 
@@ -873,6 +877,7 @@ class RepoRunner(BaseAsset):
                 environment_name=self.org_login,
                 environmentid=self.org_node_id,
                 query_repositories=f"MATCH p=(:GH_Repository {{node_id:'{self.repository_node_id}'}})-[:GH_CanUseRunner]->(:GH_RepoRunner {{node_id:'{rid}'}}) RETURN p",
+                query_jobs=f"MATCH p=(:GH_WorkflowJob)-[:GH_RunsOn]->(:GH_Runner {{node_id:'{rid}'}}) RETURN p",
             ),
         )
 

{openhound_github-0.7.3 → openhound_github-0.8.0}/src/openhound_github/models/workflow.py

@@ -43,6 +43,7 @@ SECRET_REFERENCE_RE = re.compile(r"\$\{\{\s*secrets\.(\w+)\s*\}\}")
 VARIABLE_REFERENCE_RE = re.compile(r"\$\{\{\s*vars\.(\w+)\s*\}\}")
 ACTION_RE = re.compile(r"^(?P<owner>[^/]+)/(?P<name>[^@]+)@(?P<ref>.+)$")
 PINNED_REF_RE = re.compile(r"^[0-9a-f]{40}$")
+TEMPLATE_RE = re.compile(r"\$\{\{\s*[^}]+?\s*\}\}")
 
 
 class WorkflowStepDefinition(BaseModel):
@@ -94,6 +95,49 @@ class RunsOn(BaseModel):
     labels: list[str] | str | None = None
 
 
+class RunsOnSelector(BaseModel):
+    group: str | None = None
+    labels: list[str] = Field(default_factory=list)
+    is_dynamic: bool = False
+
+
+def parse_runs_on_selector(value: Any) -> RunsOnSelector:
+    """Normalize a workflow job's runs-on declaration without losing group data."""
+    if value is None:
+        return RunsOnSelector()
+
+    if isinstance(value, RunsOn):
+        value = value.model_dump()
+
+    group: str | None = None
+    labels: list[str] = []
+
+    if isinstance(value, str):
+        labels = [value]
+    elif isinstance(value, list):
+        labels = [str(item) for item in value]
+    elif isinstance(value, dict):
+        raw_group = value.get("group")
+        if raw_group is not None:
+            group = str(raw_group)
+
+        raw_labels = value.get("labels")
+        if isinstance(raw_labels, str):
+            labels = [raw_labels]
+        elif isinstance(raw_labels, list):
+            labels = [str(item) for item in raw_labels]
+        elif raw_labels is not None:
+            labels = [str(raw_labels)]
+    else:
+        labels = [str(value)]
+
+    is_dynamic = any(TEMPLATE_RE.search(item) for item in labels)
+    if group:
+        is_dynamic = is_dynamic or bool(TEMPLATE_RE.search(group))
+
+    return RunsOnSelector(group=group, labels=labels, is_dynamic=is_dynamic)
+
+
 class WorkflowJobDefinition(BaseModel):
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
@@ -149,6 +193,10 @@ class WorkflowJobDefinition(BaseModel):
     def container_value(self) -> str | None:
         return str(self.container) if self.container else None
 
+    @property
+    def runs_on_selector(self) -> RunsOnSelector:
+        return parse_runs_on_selector(self.runs_on)
+
 
 class WorkflowDocument(BaseModel):
     model_config = ConfigDict(extra="allow")
@@ -498,6 +546,7 @@ class Workflow(BaseAsset):
         }
         rows = []
         for job_key, job in document.jobs.items():
+            runs_on_selector = job.runs_on_selector
             secret_refs = []
             variable_refs = []
             secret_refs.extend(
@@ -514,6 +563,9 @@ class Workflow(BaseAsset):
                     "name": f"{self.repository_name}\\{job_key}",
                     "job_key": job_key,
                     "runs_on": job.runs_on,
+                    "runs_on_group": runs_on_selector.group,
+                    "runs_on_labels": runs_on_selector.labels or None,
+                    "runs_on_is_dynamic": runs_on_selector.is_dynamic,
                     "container": job.container_value,
                     "environment": job.environment_name,
                     "permissions": job.permissions