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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openhound-github
-Version: 0.5.2
+Version: 0.5.3
 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.5.2 → openhound_github-0.5.3}/descriptions/edges/GH_ApprovesDeploymentTo.md

@@ -4,4 +4,4 @@ The non-traversable GH_ApprovesDeploymentTo edge represents that a user or team
 
 This edge is emitted from GH_User or GH_Team nodes to GH_Environment nodes when the environment includes a required reviewer protection rule. Required reviewers act as an approval gate before jobs referencing the environment can continue.
 
-The edge is non-traversable because it records reviewer configuration rather than direct deployment access. When self-review is allowed, the same reviewer may also receive a traversable GH_CanDeployToEnvironment edge because they can satisfy the approval gate themselves. When prevent_self_review is enabled, GH_ApprovesDeploymentTo remains context only because the split-principal approval flow is not currently modeled.
+The edge is non-traversable because it records reviewer configuration rather than direct deployment access. When self-review is allowed, the same reviewer may also receive a traversable GH_CanDeployToEnvironment edge only if they can also supply deployable code through GH_CanCreateBranch or GH_CanWriteBranch under the environment's branch policy. When prevent_self_review is enabled, GH_ApprovesDeploymentTo remains context only because the split-principal approval flow is not currently modeled.

openhound_github-0.5.3/descriptions/edges/GH_CanDeployToEnvironment.md

@@ -0,0 +1,9 @@
+## General Information
+
+The traversable GH_CanDeployToEnvironment edge represents the ability for a repository, branch, repository role, or reviewer to satisfy the modeled deployment constraints for a GitHub Environment.
+
+This edge is computed from environment deployment branch policy, branch protection state, required reviewer behavior, and administrator bypass behavior. For environments without required reviewers, unrestricted environments emit repository and branch edges, protected-branch-only environments emit edges only for protected branches unless no branch protection rules exist, and custom branch policies emit edges only for matching branches.
+
+When required reviewers are configured and self-review is allowed, a configured GH_User or GH_Team reviewer receives GH_CanDeployToEnvironment only when the same actor can also supply deployable code. For unrestricted environments this means the actor can create a branch in the repository. For protected-branch-only or custom branch policy environments this means the actor can write to an eligible branch under the existing GH_CanWriteBranch rules.
+
+Self-review alone is not sufficient for this edge. GH_ApprovesDeploymentTo remains the non-traversable representation of reviewer authority, while GH_CanDeployToEnvironment represents the combined ability to satisfy both the approval gate and the code-supply path. When prevent_self_review is enabled, no direct deploy edge is emitted for the reviewer because the required split-principal flow is not currently modeled.

{openhound_github-0.5.2 → openhound_github-0.5.3}/extension/schema.json

@@ -1042,7 +1042,7 @@
     },
     {
       "name": "GH_CanDeployToEnvironment",
-      "description": "[Computed] Repository, branch, repo role, or self-approving reviewer can deploy to this GitHub environment after evaluating deployment branch policy, reviewer gates, and admin bypass behavior",
+      "description": "[Computed] Repository, branch, repo role, or reviewer can deploy to this GitHub environment after evaluating deployment branch policy, reviewer gates, and admin bypass behavior; reviewer edges require both self-approval and a deployable code path",
       "is_traversable": true
     },
     {

{openhound_github-0.5.2 → openhound_github-0.5.3}/src/openhound_github/lookup.py

@@ -1,3 +1,4 @@
+import json
 from functools import lru_cache
 
 import duckdb
@@ -584,6 +585,265 @@ class GithubLookup(LookupManager):
             [repository_node_id],
         )
 
+    @lru_cache
+    def environment_branch_policy_names(self, environment_node_id: str):
+        return self._find_all_objects(
+            f"""
+            SELECT name
+            FROM {self.schema}.environment_branch_policies
+            WHERE environment_node_id = ?
+            """,
+            [environment_node_id],
+        )
+
+    @lru_cache
+    def reviewer_repo_role_assignments(
+        self, reviewer_node_id: str, reviewer_kind: str, repository_node_id: str
+    ):
+        reviewer_kind = reviewer_kind.lower()
+        return self._find_all_objects(
+            f"""
+            WITH RECURSIVE
+            repository_org(org_login) AS (
+                SELECT org_login
+                FROM {self.schema}.repositories
+                WHERE node_id = ?
+            ),
+            seed_teams(team_id) AS (
+                SELECT ? WHERE ? = 'team'
+
+                UNION
+
+                SELECT tm.team_id
+                FROM {self.schema}.team_members tm
+                WHERE ? = 'user'
+                  AND tm.id = ?
+            ),
+            actor_teams(team_id) AS (
+                SELECT team_id
+                FROM seed_teams
+
+                UNION
+
+                SELECT json_extract_string(t.parent_team, '$.id')
+                FROM {self.schema}.teams t
+                JOIN actor_teams actor_team ON t.id = actor_team.team_id
+                WHERE t.parent_team IS NOT NULL
+                  AND json_extract_string(t.parent_team, '$.id') IS NOT NULL
+            ),
+            direct_repo_roles(
+                assignment_actor_id,
+                role_id,
+                role_name,
+                base_role,
+                role_permissions
+            ) AS (
+                SELECT DISTINCT
+                    rra.node_id,
+                    rr.id,
+                    rra.role_name,
+                    coalesce(rra.base_role, rr.base_role),
+                    rra.role_permissions
+                FROM {self.schema}.repo_role_assignments rra
+                LEFT JOIN {self.schema}.repo_roles rr
+                  ON rr.repository_node_id = rra.repo_node_id
+                 AND rr.name = rra.role_name
+                WHERE rra.repo_node_id = ?
+                  AND (
+                      (lower(rra.assignee_type) = ? AND rra.node_id = ?)
+                      OR (
+                          lower(rra.assignee_type) = 'team'
+                          AND rra.node_id IN (SELECT team_id FROM actor_teams)
+                      )
+                  )
+            ),
+            actor_org_roles(assignment_actor_id, org_role_name, base_role) AS (
+                SELECT
+                    u.id,
+                    CASE WHEN u.role = 'ADMIN' THEN 'owners' ELSE 'members' END,
+                    org_role.base_role
+                FROM {self.schema}.users u
+                JOIN repository_org repo_org ON repo_org.org_login = u.org_login
+                JOIN {self.schema}.org_roles org_role
+                  ON org_role.org_login = u.org_login
+                 AND org_role.name = CASE
+                     WHEN u.role = 'ADMIN' THEN 'owners'
+                     ELSE 'members'
+                 END
+                WHERE ? = 'user'
+                  AND u.id = ?
+
+                UNION
+
+                SELECT
+                    orm.node_id,
+                    orm.org_role_name,
+                    org_role.base_role
+                FROM {self.schema}.org_role_members orm
+                JOIN repository_org repo_org ON repo_org.org_login = orm.org_login
+                JOIN {self.schema}.org_roles org_role
+                  ON org_role.org_login = orm.org_login
+                 AND org_role.name = orm.org_role_name
+                WHERE ? = 'user'
+                  AND orm.node_id = ?
+
+                UNION
+
+                SELECT
+                    ort.node_id,
+                    ort.org_role_name,
+                    org_role.base_role
+                FROM {self.schema}.org_role_teams ort
+                JOIN repository_org repo_org ON repo_org.org_login = ort.org_login
+                JOIN {self.schema}.org_roles org_role
+                  ON org_role.org_login = ort.org_login
+                 AND org_role.name = ort.org_role_name
+                WHERE ort.node_id IN (SELECT team_id FROM actor_teams)
+            ),
+            org_repo_roles(
+                assignment_actor_id,
+                role_id,
+                role_name,
+                base_role,
+                role_permissions
+            ) AS (
+                SELECT DISTINCT
+                    actor_org_role.assignment_actor_id,
+                    rr.id,
+                    rr.name,
+                    rr.base_role,
+                    rr.permissions
+                FROM actor_org_roles actor_org_role
+                JOIN {self.schema}.repo_roles rr
+                  ON rr.repository_node_id = ?
+                 AND rr.name = actor_org_role.base_role
+            )
+            SELECT * FROM direct_repo_roles
+            UNION
+            SELECT * FROM org_repo_roles
+            """,
+            [
+                repository_node_id,
+                reviewer_node_id,
+                reviewer_kind,
+                reviewer_kind,
+                reviewer_node_id,
+                repository_node_id,
+                reviewer_kind,
+                reviewer_node_id,
+                reviewer_kind,
+                reviewer_node_id,
+                reviewer_kind,
+                reviewer_node_id,
+                repository_node_id,
+            ],
+        )
+
+    @staticmethod
+    def _role_permissions(raw_permissions) -> set[str]:
+        if raw_permissions is None:
+            return set()
+        if isinstance(raw_permissions, str):
+            try:
+                raw_permissions = json.loads(raw_permissions)
+            except json.JSONDecodeError:
+                return set()
+        if not isinstance(raw_permissions, list):
+            return set()
+        return {str(permission) for permission in raw_permissions}
+
+    @lru_cache
+    def reviewer_deployment_path(
+        self,
+        reviewer_node_id: str,
+        reviewer_kind: str,
+        repository_node_id: str,
+        eligible_branch_ids: tuple[str, ...],
+        allow_create_branch: bool,
+    ) -> tuple[str, str | None] | None:
+        if not self.repository_default_branch_collected(repository_node_id):
+            return None
+
+        eligible_branches = set(eligible_branch_ids)
+        write_roles = {"write", "maintain", "admin"}
+        bypass_roles = {"maintain"}
+
+        for (
+            assignment_actor_id,
+            role_id,
+            role_name,
+            base_role,
+            raw_permissions,
+        ) in self.reviewer_repo_role_assignments(
+            reviewer_node_id, reviewer_kind, repository_node_id
+        ):
+            permissions = self._role_permissions(raw_permissions)
+            has_write_access = role_name in write_roles or base_role in write_roles
+            if not has_write_access:
+                continue
+
+            if (
+                allow_create_branch
+                and role_id is not None
+                and self.role_can_create_branch(role_id, repository_node_id)
+            ):
+                return ("create_branch", None)
+
+            writable_branches = {
+                branch_id
+                for (branch_id,) in self.unprotected_branches(repository_node_id)
+            }
+
+            has_push_protected_branch = (
+                ("push_protected_branch" in permissions and base_role in write_roles)
+                or role_name in bypass_roles
+                or base_role in bypass_roles
+            )
+            has_bypass_branch_protection = (
+                "bypass_branch_protection" in permissions and base_role in write_roles
+            )
+
+            if role_name == "admin" or base_role == "admin":
+                writable_branches.update(
+                    branch_id
+                    for (branch_id,) in self._write_admin_bypass(repository_node_id)
+                )
+            if has_push_protected_branch:
+                writable_branches.update(
+                    branch_id
+                    for (branch_id,) in self._write_push_restricted_branch_bypass(
+                        repository_node_id
+                    )
+                )
+            if has_bypass_branch_protection:
+                writable_branches.update(
+                    branch_id
+                    for (branch_id,) in self._write_branch_protection_bypass(
+                        repository_node_id
+                    )
+                )
+            if has_push_protected_branch and has_bypass_branch_protection:
+                writable_branches.update(
+                    branch_id
+                    for (branch_id,) in self._write_combined_bypass(repository_node_id)
+                )
+
+            writable_branches.update(
+                branch_id
+                for (branch_id,) in self.actor_gate_bypass(
+                    assignment_actor_id,
+                    repository_node_id,
+                    has_bypass_branch_protection,
+                    has_push_protected_branch,
+                )
+            )
+
+            for branch_id in eligible_branch_ids:
+                if branch_id in writable_branches and branch_id in eligible_branches:
+                    return ("write_branch", branch_id)
+
+        return None
+
     @lru_cache
     def members_can_fork_private_repositories(self, org_login: str):
         return self._find_all_objects(

{openhound_github-0.5.2 → openhound_github-0.5.3}/src/openhound_github/main.py

@@ -59,6 +59,9 @@ def preproc(ctx: PreProcContext):
         "repo_role_assignments": "repo_role_assignments",
         "branches": "branches",
         "repo_roles": "repo_roles",
+        "users": "users",
+        "teams": "teams",
+        "team_members": "team_members",
         "saml_provider": "saml_provider",
         "applications": "applications",
         "enterprise": "enterprise",
@@ -67,8 +70,11 @@ def preproc(ctx: PreProcContext):
         "enterprise_runner_group_organizations": "enterprise_runner_group_organizations",
         "enterprise_runner_group_memberships": "enterprise_runner_group_memberships",
         "org_roles": "org_roles",
+        "org_role_members": "org_role_members",
+        "org_role_teams": "org_role_teams",
         "projected_enterprise_teams": "projected_enterprise_teams",
         "environments": "environments",
+        "environment_branch_policies": "environment_branch_policies",
         "environment_secrets": "environment_secrets",
         "environment_variables": "environment_variables",
         "organization_secrets": "organization_secrets",

{openhound_github-0.5.2 → openhound_github-0.5.3}/src/openhound_github/models/environment.py

@@ -10,6 +10,9 @@ from openhound_github.graph import GHEdgeProperties, GHNode, GHNodeProperties
 from openhound_github.kinds import edges as ek
 from openhound_github.kinds import nodes as nk
 from openhound_github.main import app
+from openhound_github.models.environment_branch_policy import (
+    matches_environment_branch_policy,
+)
 
 
 class DeploymentBranchPolicy(BaseModel):
@@ -142,14 +145,14 @@ class GHEnvironmentProperties(GHNodeProperties):
             start=nk.USER,
             end=nk.ENVIRONMENT,
             kind=ek.CAN_DEPLOY_TO_ENVIRONMENT,
-            description="Reviewer user can self-approve deployment to environment",
+            description="Reviewer user can self-approve and supply deployable code under current branch policy",
             traversable=True,
         ),
         EdgeDef(
             start=nk.TEAM,
             end=nk.ENVIRONMENT,
             kind=ek.CAN_DEPLOY_TO_ENVIRONMENT,
-            description="Reviewer team can self-approve deployment to environment",
+            description="Reviewer team can self-approve and supply deployable code under current branch policy",
             traversable=True,
         ),
         EdgeDef(
@@ -240,6 +243,53 @@ class Environment(BaseAsset):
     def reviewer_self_deployment_edges_allowed(self) -> bool:
         return self.required_reviewers and not self.prevent_self_review
 
+    @property
+    def _reviewer_eligible_branch_ids(self) -> tuple[str, ...]:
+        branches = self._lookup.branches_for_repository(self.repository_node_id)
+
+        if self.has_custom_branch_policies:
+            protected_branches_only = bool(
+                self.deployment_branch_policy
+                and self.deployment_branch_policy.protected_branches
+            )
+            policy_names = {
+                policy_name
+                for (policy_name,) in self._lookup.environment_branch_policy_names(
+                    self.node_id
+                )
+            }
+            return tuple(
+                branch_id
+                for branch_id, branch_name, protected in branches
+                if any(
+                    matches_environment_branch_policy(branch_name, policy_name)
+                    for policy_name in policy_names
+                )
+                and (not protected_branches_only or protected)
+            )
+
+        if (
+            self.deployment_branch_policy
+            and self.deployment_branch_policy.protected_branches
+        ):
+            protected_branch_ids = tuple(
+                branch_id
+                for (branch_id,) in self._lookup.branches_with_bpr(
+                    self.repository_node_id
+                )
+            )
+            if protected_branch_ids:
+                return protected_branch_ids
+
+        return tuple(branch_id for branch_id, _branch_name, _protected in branches)
+
+    @property
+    def _reviewer_can_create_branch_for_deployment(self) -> bool:
+        return not self.has_custom_branch_policies and not (
+            self.deployment_branch_policy
+            and self.deployment_branch_policy.protected_branches
+        )
+
     @property
     def as_node(self) -> GHNode:
         eid = self.node_id
@@ -313,16 +363,107 @@ class Environment(BaseAsset):
             f"RETURN p"
         )
 
-    def _reviewer_can_deploy_query(
+    def _reviewer_can_create_branch_query(
         self, reviewer_node_id: str, reviewer_kind: str
     ) -> str:
         return (
-            f"MATCH p=(:{reviewer_kind} {{node_id:'{reviewer_node_id}'}})"
-            f"-[:GH_ApprovesDeploymentTo]->"
+            f"MATCH p=(actor:{reviewer_kind} {{node_id:'{reviewer_node_id}'}})"
+            f"-[:GH_HasRole|GH_HasBaseRole|GH_MemberOf*1..]->"
+            f"(:GH_RepoRole)-[:GH_CanCreateBranch]->"
+            f"(repo:GH_Repository {{node_id:'{self.repository_node_id}'}}) "
+            f"MATCH p1=(actor)-[:GH_ApprovesDeploymentTo]->"
             f"(env:GH_Environment {{node_id:'{self.node_id}'}}) "
+            f"MATCH p2=(repo)-[:GH_Contains]->(env) "
             f"WHERE env.required_reviewers = true "
             f"AND coalesce(env.prevent_self_review, false) = false "
-            f"RETURN p"
+            f"AND coalesce(env.custom_branch_policies, false) = false "
+            f"AND coalesce(env.protected_branches, false) = false "
+            f"RETURN p, p1, p2"
+        )
+
+    def _reviewer_can_write_branch_query(
+        self, reviewer_node_id: str, reviewer_kind: str, branch_id: str
+    ) -> str:
+        actor_path = (
+            f"MATCH p=(actor:{reviewer_kind} {{node_id:'{reviewer_node_id}'}})"
+            f"-[:GH_HasRole|GH_HasBaseRole|GH_MemberOf|GH_CanWriteBranch*1..]->"
+            f"(branch:GH_Branch {{node_id:'{branch_id}'}}) "
+            f"MATCH p1=(actor)-[:GH_ApprovesDeploymentTo]->"
+            f"(env:GH_Environment {{node_id:'{self.node_id}'}}) "
+        )
+        reviewer_policy = (
+            "WHERE env.required_reviewers = true "
+            "AND coalesce(env.prevent_self_review, false) = false "
+        )
+
+        if self.has_custom_branch_policies:
+            custom_policy_path = (
+                "MATCH p2=(branch)-[:GH_MatchesEnvironmentPolicy]->"
+                "(:GH_EnvironmentBranchPolicy)<-[:GH_Contains]-(env) "
+            )
+            if (
+                self.deployment_branch_policy
+                and self.deployment_branch_policy.protected_branches
+            ):
+                return (
+                    actor_path
+                    + custom_policy_path
+                    + "MATCH p3=(branch)<-[:GH_ProtectedBy]-(:GH_BranchProtectionRule) "
+                    + reviewer_policy
+                    + "AND env.custom_branch_policies = true "
+                    + "AND env.protected_branches = true "
+                    + "RETURN p, p1, p2, p3"
+                )
+
+            return (
+                actor_path
+                + custom_policy_path
+                + reviewer_policy
+                + "AND env.custom_branch_policies = true "
+                + "AND coalesce(env.protected_branches, false) = false "
+                + "RETURN p, p1, p2"
+            )
+
+        if (
+            self.deployment_branch_policy
+            and self.deployment_branch_policy.protected_branches
+        ):
+            if self._lookup.branches_with_bpr(self.repository_node_id):
+                return (
+                    actor_path
+                    + f"MATCH p2=(repo:GH_Repository {{node_id:'{self.repository_node_id}'}})"
+                    f"-[:GH_Contains]->(branch)<-[:GH_ProtectedBy]-(:GH_BranchProtectionRule) "
+                    f"MATCH p3=(repo)-[:GH_Contains]->(env) "
+                    + reviewer_policy
+                    + "AND env.protected_branches = true "
+                    + "AND coalesce(env.custom_branch_policies, false) = false "
+                    + "RETURN p, p1, p2, p3"
+                )
+
+            return (
+                actor_path
+                + f"MATCH p2=(repo:GH_Repository {{node_id:'{self.repository_node_id}'}})"
+                f"-[:GH_Contains]->(branch) "
+                f"MATCH p3=(repo)-[:GH_Contains]->(env) "
+                + reviewer_policy
+                + "AND env.protected_branches = true "
+                + "AND coalesce(env.custom_branch_policies, false) = false "
+                + "AND NOT EXISTS { "
+                + "MATCH (repo)-[:GH_Contains]->(:GH_Branch)"
+                + "<-[:GH_ProtectedBy]-(:GH_BranchProtectionRule) "
+                + "} "
+                + "RETURN p, p1, p2, p3"
+            )
+
+        return (
+            actor_path
+            + f"MATCH p2=(repo:GH_Repository {{node_id:'{self.repository_node_id}'}})"
+            f"-[:GH_Contains]->(branch) "
+            f"MATCH p3=(repo)-[:GH_Contains]->(env) "
+            + reviewer_policy
+            + "AND coalesce(env.custom_branch_policies, false) = false "
+            + "AND coalesce(env.protected_branches, false) = false "
+            + "RETURN p, p1, p2, p3"
         )
 
     def _protected_branches_fallback_repo_query(self) -> str:
@@ -480,6 +621,26 @@ class Environment(BaseAsset):
 
             if self.reviewer_self_deployment_edges_allowed:
                 reviewer_kind = nk.USER if reviewer_type == "user" else nk.TEAM
+                deployment_path = self._lookup.reviewer_deployment_path(
+                    reviewer_node_id,
+                    reviewer_type,
+                    self.repository_node_id,
+                    self._reviewer_eligible_branch_ids,
+                    self._reviewer_can_create_branch_for_deployment,
+                )
+                if deployment_path is None:
+                    continue
+
+                path_type, branch_id = deployment_path
+                query_composition = (
+                    self._reviewer_can_create_branch_query(
+                        reviewer_node_id, reviewer_kind
+                    )
+                    if path_type == "create_branch"
+                    else self._reviewer_can_write_branch_query(
+                        reviewer_node_id, reviewer_kind, branch_id or ""
+                    )
+                )
                 yield Edge(
                     kind=ek.CAN_DEPLOY_TO_ENVIRONMENT,
                     start=EdgePath(value=reviewer_node_id, match_by="id"),
@@ -487,8 +648,6 @@ class Environment(BaseAsset):
                     properties=GHEdgeProperties(
                         traversable=True,
                         composed=True,
-                        query_composition=self._reviewer_can_deploy_query(
-                            reviewer_node_id, reviewer_kind
-                        ),
+                        query_composition=query_composition,
                     ),
                 )

{openhound_github-0.5.2 → openhound_github-0.5.3}/src/openhound_github/models/environment_branch_policy.py

@@ -11,6 +11,14 @@ from openhound_github.main import app
 
 # from openhound_github.helpers import _b64
 
+
+def matches_environment_branch_policy(branch_name: str, policy_name: str) -> bool:
+    return PurePosixPath(f"/{branch_name}").full_match(
+        f"/{policy_name}",
+        case_sensitive=True,
+    )
+
+
 @dataclass
 class GHEnvironmentBranchPolicyProperties(GHNodeProperties):
     environment_name: str | None = None
@@ -88,10 +96,7 @@ class EnvironmentBranchPolicy(BaseAsset):
         return required_reviewers
 
     def matches_branch(self, branch_name: str) -> bool:
-        return PurePosixPath(f"/{branch_name}").full_match(
-            f"/{self.name}",
-            case_sensitive=True,
-        )
+        return matches_environment_branch_policy(branch_name, self.name)
 
     @property
     def as_node(self) -> GHNode: