Full Report
Learn about the process of preventing security issues by changing things outside of your environment by looking at how a misconfiguration was occurring when Github Actions were integrated with AWS IAM roles and the improvements made that have now made this misconfiguration much less likely.
Analysis Summary
# Best Practices: Securing AWS IAM Roles for GitHub Actions OIDC Integration
## Overview
This summary details best practices and necessary remediation steps to secure AWS IAM Role Trust Policies being used with GitHub Actions OpenID Connect (OIDC) integration, specifically addressing the critical vulnerability where the missing `sub` condition allows unauthorized assumption of the role by any repository.
## Key Recommendations
### Immediate Actions
1. **Audit Existing Trust Policies:** Immediately scan all IAM Role Trust Policies configured for OIDC integration with GitHub Actions to identify roles missing the `Condition` block containing the `StringEquals` check on the `sub` attribute.
2. **Apply the `sub` Condition:** For all identified vulnerable roles, update the Trust Policy immediately to include the `Condition` block specifying the exact repository path (e.g., `repo:owner/repo-name:ref:refs/heads/*`).
3. **Engage Documentation Owners:** If using infrastructure-as-code (IaC) like Terraform or referencing popular tutorials, report the flawed configuration examples to the authors/maintainers to ensure corrections are propagated widely (as seen by successful engagements with tutorial authors).
### Short-term Improvements (1-3 months)
1. **Update IaC Templates:** Review and correct all IaC templates (e.g., Terraform, CloudFormation) used to provision AWS OIDC integrations. Ensure that templates explicitly include the necessary repository-specific `sub` condition.
2. **Implement Provider-Level Warnings (If Applicable):** If using tools like Terraform, integrate or utilize proposed mechanisms (like custom or planned semgrep rules) that flag the potential security issue related to duplicate map keys in JSON configurations, which can silently remove the `sub` condition.
3. **Leverage AWS Access Analyzer:** Ensure the Access Analyzer Policy Validator is active for manual IAM role edits in the console, as it provides warnings for missing repository conditions during creation or manual modification.
### Long-term Strategy (3+ months)
1. **Monitor Community Fixes and Enforcement:** Stay current with public advisories (like AWS enforcement dates) and security bulletins from tool vendors (like HashiCorp) regarding how they plan to warn users about this or similar silent JSON parsing issues.
2. **Strengthen Trust Policy Granularity:** Beyond the `sub` condition, review other conditions (like `aud` or `typ` if applicable in future provider configurations) to ensure the least privilege principle is strictly enforced across the entire trust relationship.
3. **Adopt Cloud Security Posture Management (CSPM):** Implement automated CSPM tools (like Wiz or similar) capable of continuously scanning and auditing cloud configurations against known security benchmarks for OIDC trust relationships.
## Implementation Guidance
### For Small Organizations
- **Direct Console/CLI Fixes:** Focus primarily on directly correcting the Trust Policies in the AWS console or via AWS CLI/SDK, as IaC adoption might be minimal.
- **Prioritize High-Privilege Roles:** Audit and fix the trust policies attached to roles that grant the broadest permissions first.
- **Utilize AWS Notifications:** Ensure you are subscribed to AWS security notifications, as AWS will notify customers directly about these critical misconfigurations.
### For Medium Organizations
- **Mandate IaC Review:** If IaC is used, immediately mandate a review cycle for all OIDC provisioning templates. Integrate static analysis scanning focused on these specific trust policy structures.
- **Automated Discovery:** Deploy simple scripts or leverage native AWS services (like Config Rules or Security Hub custom checks) that specifically look for IAM policies where `Principal` uses an OIDC provider URI and lacks a `Condition` block referencing the repository's `sub` claim.
### For Large Enterprises
- **Vendor Coordination:** Work with IaC tool vendors (if possible) to incorporate security checks directly into their provider logic or module definitions to prevent generating invalid policies.
- **Proactive Wormhole Testing:** Develop internal "honeypot" OIDC roles configured with the known misconfiguration to proactively scan for exploitation attempts before attackers do.
- **Establish Policy Guardrails:** Implement preventive guardrails using AWS Service Control Policies (SCPs) or Organization Policies where feasible, restricting the creation of OIDC trust relationships that do not adhere to baseline security requirements.
## Configuration Examples
The *Correct* IAM Role Trust Policy for GitHub Actions OIDC authentication should include the `sub` condition, for example:
json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:sub": "repo:OWNER/REPO_NAME:ref:refs/heads/main"
}
}
}
]
}
**Note:** The *misconfiguration* occurs when the entire `"Condition"` block is absent or the required `StringEquals` statement on `token.actions.githubusercontent.com:sub` is missing, allowing *any* repository to assume the role.
## Compliance Alignment
- **NIST SP 800-53 (Rev. 5):** Aligns with **IA-2 (Identification and Authentication (Organizational Users))** and **AC-2 (Account Management)** by strictly controlling federated identity access.
- **ISO/IEC 27001:** Addresses requirements under **A.9 (Access Control)** and **A.14 (System Acquisition, Development and Maintenance)** regarding secure configuration management and least privilege.
- **CIS AWS Foundations Benchmark:** Relates to ensuring overly permissive IAM policies are corrected and that federation is configured securely.
## Common Pitfalls to Avoid
1. **Silent IaC Overwrites:** Be extremely cautious when defining JSON resources in IaC, particularly using tools where duplicate keys in a map definition are silently ignored, leading to mission-critical conditions (like the `sub` check) being dropped.
2. **Incomplete Remediation:** Assuming that all instances of the vulnerable configuration are only in manually edited policies. Actively search IaC repositories and configuration management tools for existing flawed definitions.
3. **Relying Solely on Console Warnings:** While AWS Console's Access Analyzer provides warnings during manual edits, configurations deployed via code will bypass this unless specifically integrated into the CI/CD pipeline or IaC tooling configuration phase.
## Resources
- AWS IAM Documentation on Creating Roles for Web Identity Federation (Search for the official documentation detailing the OIDC provider setup).
- HashiCorp Security Bulletin regarding duplicate map key handling (Search for HCSEC-2023-26).
- Security research findings detailing the requirement for the `sub` condition in AWS OIDC trust policies.