AWS IAM Role Trust Relationship for GitHub Actions

Description

This policy ensures that IAM roles used with GitHub Actions are securely configured to prevent unauthorized access to AWS resources. It validates trust relationships by checking for proper audience (aud) restrictions, ensuring it is set to sts.amazonaws.com, and subject (sub) conditions, confirming they are scoped to specific repositories or environments. Misconfigurations, such as overly permissive wildcards or missing conditions, can allow unauthorized repositories to assume roles, leading to potential data breaches or compliance violations. By enforcing these checks, the policy mitigates risks of exploitation, enhances security posture, and protects critical AWS resources from external threats.

Query · python

import json

from panther_base_helpers import deep_get

# Add/remove pairs as desired
ALLOWED_ORG_REPO_PAIRS = ["org/repo", "allowed-org-example/allowed-repo-example"]


def policy(resource):
    # check if resource.AssumRolePolicyDocument is a string, and if so convert to json
    if isinstance(resource.get("AssumeRolePolicyDocument"), str):
        policy_document = json.loads(resource.get("AssumeRolePolicyDocument", {}))
    else:
        policy_document = resource.get("AssumeRolePolicyDocument", {})
    assume_role_policy = policy_document.get("Statement", [])

    for statement in assume_role_policy:
        # only check for Allow sts:AssumeRoleWithWebIdentity
        if (
            statement.get("Effect") != "Allow"
            or statement.get("Action") != "sts:AssumeRoleWithWebIdentity"
        ):
            continue

        principal = deep_get(statement, "Principal", "Federated")
        audience = deep_get(
            statement, "Condition", "StringEquals", "token.actions.githubusercontent.com:aud"
        )
        subject = deep_get(
            statement,
            "Condition",
            "StringLike",
            "token.actions.githubusercontent.com:sub",
            default="",
        ) or deep_get(
            statement,
            "Condition",
            "StringEquals",
            "token.actions.githubusercontent.com:sub",
            default="",
        )

        if subject.startswith("repo:"):
            # repo subjects must have github as the principal and sts.amazonaws.com as the audience
            if any(
                [
                    "oidc-provider/token.actions.githubusercontent.com" not in principal,
                    audience != "sts.amazonaws.com",
                    (
                        "*" in subject
                        and not any(
                            subject.startswith(f"repo:{org_repo}:*")
                            for org_repo in ALLOWED_ORG_REPO_PAIRS
                        )
                    ),
                ]
            ):
                return False
        else:
            # non-repo subjects must not have github as the principal
            if "oidc-provider/token.actions.githubusercontent.com" in principal:
                return False

    return True

Analyst notes

To fix roles flagged by this policy: 1. Update the trust relationship of the flagged IAM role in the AWS Management Console or CLI. 2. Add a Condition block with 'StringLike' or 'StringEquals' for 'token.actions.githubusercontent.com:sub'. 3. Ensure the audience is set to 'sts.amazonaws.com'. 4. Avoid overly permissive wildcards in the sub condition.

Detection tier

Not a detection

This rule makes no claim about adversary activity — it asserts configuration, suppresses an alert, or records a policy violation — so it sits at no rung of the pyramid.

Metadata

Source: panther-labs/panther-analysis
License: Apache 2.0
Severity: High
Status: Experimental
Query type: python
Created: 2025-01-15
Modified: 2025-04-29
Authored by: panther-labs
Source ID: —
Upstream: policies/aws_iam_policies/aws_iam_role_github_actions_trust.yml
Type: policy
Version: 1