Skip to content

Commit 983e28a

Browse files
yhakbaryhakbar
committed
docs: Migrating out AWS specific security controls for Pipelines to Account Factory
1 parent 80c4daa commit 983e28a

File tree

2 files changed

+230
-1
lines changed

2 files changed

+230
-1
lines changed

‎docs/2.0/docs/accountfactory/architecture/security-controls.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# Controls
2+
3+
Gruntwork Account Factory employs a defense-in-depth approach to secure workflows across both GitHub and GitLab platforms. This document outlines the controls Pipelines uses to ensure that only infrastructure written in code and approved by a reviewer can be deployed to your AWS accounts.
4+
5+
## Least privilege principle
6+
7+
Pipelines adheres to the principle of least privilege, granting only the necessary permissions for infrastructure actions.
8+
9+
By default, the only repository/group required to interact with infrastructure using Pipelines in Gruntwork Account Factory is the `infrastructure-live-root` repository/group. This contains infrastructure code for `management`, `logs`, `security`, and `shared` accounts. Access should be limited to a small, trusted group responsible for defining critical infrastructure, similar to the role of the `root` user in Unix systems.
10+
11+
## Platform-Specific Access Controls
12+
13+
import Tabs from "@theme/Tabs"
14+
import TabItem from "@theme/TabItem"
15+
16+
<Tabs groupId="platform">
17+
<TabItem value="github" label="GitHub" default>
18+
19+
- The AWS IAM role assumed via OIDC when pull requests are opened or updated has a trust policy that restricts access to the repository itself and provides read-only permissions
20+
- The AWS IAM role assumed via OIDC when pull requests are merged into the `main` branch has a trust policy limiting access to the repository's `main` branch and granting write permissions
21+
- Branch protection rules can be configured to require reviews and status checks
22+
- GitHub App or machine user authentication options available
23+
24+
</TabItem>
25+
<TabItem value="gitlab" label="GitLab">
26+
27+
- The AWS IAM role assumed via OIDC when merge requests are opened or updated has a trust policy that restricts access to the group itself and provides read-only permissions
28+
- The AWS IAM role assumed via OIDC when merge requests are merged into the `main` branch has a trust policy limiting access to the group's `main` branch and granting write permissions
29+
- Protected branches can be configured to require approvals and pipeline success
30+
- Machine user authentication required with group-level access configuration
31+
32+
</TabItem>
33+
</Tabs>
34+
35+
## Infrastructure access control
36+
37+
An optional `infrastructure-live-access-control` repository/group can manage access control for infrastructure provisioned in AWS accounts. Using this is a best practice for centralized and auditable access management.
38+
39+
- Access to the `main` branch should be restricted to a small, trusted group managing infrastructure access
40+
- The same least privilege principles apply: roles assumed for pull/merge requests have read-only permissions, while roles for merged changes have write permissions
41+
42+
Unlike the infrastructure-live-root repository, this repository focuses on managing access control rather than defining infrastructure. You might grant write access to a broader group for managing access while maintaining tight control over the main branch. Encourage collaboration between platform teams and application engineers to review and refine access control continuously.
43+
44+
## Token Strategy
45+
46+
<Tabs groupId="platform">
47+
<TabItem value="github" label="GitHub" default>
48+
49+
### GitHub App Installation Strategy (Recommended)
50+
51+
No tokens are required when using the GitHub App.
52+
53+
### Machine Users Installation Strategy
54+
55+
Requires the following tokens be created:
56+
57+
- `PIPELINES_READ_TOKEN`: Classic PAT with read access to required repositories
58+
- `INFRA_ROOT_WRITE_TOKEN`: Fine-grained PAT with read/write access to infrastructure repositories
59+
- `ORG_REPO_ADMIN_TOKEN`: Fine-grained PAT with admin access for repository management
60+
61+
See [Setup via Machine Users](/2.0/docs/pipelines/installation/viamachineusers.md) for more details.
62+
63+
</TabItem>
64+
<TabItem value="gitlab" label="GitLab">
65+
66+
Requires the following tokens be created:
67+
68+
- `PIPELINES_GITLAB_TOKEN`: A GitLab access token with `api` scope
69+
- `PIPELINES_GITLAB_READ_TOKEN`: A GitLab access token with `read_repository` scope
70+
71+
See [Setup via Machine Users](/2.0/docs/pipelines/installation/viamachineusers) for more details.
72+
73+
Pipelines will also require access to Gruntwork's GitHub repositories, however those tokens are generated at runtime via the Gruntwork Management Portal.
74+
75+
</TabItem>
76+
</Tabs>
77+
78+
## AWS credentials
79+
80+
Pipelines requires IAM roles configured with trust policies to use OpenID Connect (OIDC) with your CI/CD platform. This eliminates the need for long-lived AWS credentials stored as secrets.
81+
82+
### OpenID Connect Configuration
83+
84+
Pipelines provisions an OpenID Connect identity provider in AWS IAM for each account, setting GitHub/GitLab as the provider and restricting the audience to AWS STS and your GitHub/GitLab organization. The Pipelines IAM role's trust policy ensures:
85+
86+
- Only a single repository in your GitHub/GitLab organization can assume the role for plans.
87+
- Only a single branch can assume the role for applies/destroys.
88+
89+
For more details, see the [official AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). Below is an example of a trust policy used by Pipelines.
90+
91+
<Tabs groupId="platform">
92+
<TabItem value="github" label="GitHub" default>
93+
94+
```json
95+
{
96+
"Version": "2012-10-17",
97+
"Statement": [
98+
{
99+
"Sid": "",
100+
"Effect": "Allow",
101+
"Principal": {
102+
"Federated": "arn:aws:iam::0123456789012:oidc-provider/token.actions.githubusercontent.com"
103+
},
104+
"Action": "sts:AssumeRoleWithWebIdentity",
105+
"Condition": {
106+
"StringLike": {
107+
"token.actions.githubusercontent.com:sub": "repo:acme/infrastructure-live-root:ref:*"
108+
}
109+
}
110+
}
111+
]
112+
}
113+
```
114+
115+
</TabItem>
116+
117+
<TabItem value="gitlab" label="GitLab">
118+
119+
```json
120+
{
121+
"Version": "2012-10-17",
122+
"Statement": [
123+
{
124+
"Sid": "",
125+
"Effect": "Allow",
126+
"Principal": {
127+
"Federated": "arn:aws:iam::0123456789012:oidc-provider/gitlab.com"
128+
},
129+
"Action": "sts:AssumeRoleWithWebIdentity",
130+
"Condition": {
131+
"StringLike": {
132+
"gitlab.com:sub": "project_path:acme/projectprefix*:*"
133+
}
134+
}
135+
}
136+
]
137+
}
138+
139+
140+
```
141+
142+
</TabItem>
143+
</Tabs>
144+
145+
Refer to [Configuring OpenId Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) for additional details.
146+
147+
### Roles provisioned by DevOps Foundations
148+
149+
Pipelines automatically provisions specific roles in AWS accounts to support required infrastructure operations. These roles follow the naming pattern `<repository-allowed-to-use-the-role>-pipelines-<permissions>`.
150+
151+
For example:
152+
153+
- The `root-pipelines-plan` role is used by Pipelines to plan changes in the `infrastructure-live-root` repository.
154+
155+
These roles are designed to operate in a single repository and include a trust policy that only permits GitHub Actions workflows triggered by that repository to assume the role. Each role is provisioned in pairs:
156+
157+
- `plan` roles, with read-only permissions, are used to execute Terragrunt plans for open pull requests.
158+
- `apply` roles, with read/write permissions, are used to apply or destroy infrastructure changes for merged pull requests or direct pushes to the deploy branch (commonly `main`).
159+
160+
This separation ensures that controls like [branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) and [CODEOWNERS files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) can effectively govern infrastructure changes.
161+
162+
#### `root-pipelines-plan`
163+
164+
A read-only plan role for the `infrastructure-live-root` repository.
165+
166+
- This role is one of the first created when setting up DevOps Foundations. It is provisioned manually by the customer during the platform setup process.
167+
- It exists in all accounts and handles tasks necessary for setting up AWS accounts.
168+
- These roles are highly permissive among read-only roles as they manage foundational AWS account setups.
169+
170+
#### `root-pipelines-apply`
171+
172+
A read/write apply role for the `infrastructure-live-root` repository.
173+
174+
- Like the plan role, this is one of the initial roles created during setup.
175+
- It is broadly permissive to support foundational account setups and bootstrapping.
176+
177+
#### `access-control-pipelines-plan`
178+
179+
A read-only plan role for the `infrastructure-live-access-control` repository.
180+
181+
- These roles are provisioned for new accounts but are not included in core accounts such as `management`, `logs`, `security`, or `shared`.
182+
- They manage IAM roles and policies for vended accounts, facilitating infrastructure access control.
183+
184+
#### `access-control-pipelines-apply`
185+
186+
A read/write apply role for the `infrastructure-live-access-control` repository.
187+
188+
- Similar to the plan role, these roles are provisioned for vended accounts but excluded from core accounts.
189+
- They have permissions to manage IAM roles and policies for the accounts where they are provisioned.
190+
191+
#### `delegated-pipelines-plan`
192+
193+
A read-only plan role for delegated repositories, used by Pipelines Enterprise customers.
194+
195+
- These roles are pre-configured to have minimal permissions, primarily for managing OpenTofu/Terraform state.
196+
- A pull request will be opened in `infrastructure-live-access-control` during provisioning include documentation for adding additional permissions if necessary.
197+
- Users should ensure that only the necessary _read-only_ permissions are granted for the specific delegated repository.
198+
199+
:::note
200+
201+
These roles have almost no permissions by default. They are pre-configured by default to only have access to OpenTofu/Terraform state, and the pull requests that are opened to provision them include documentation on how to add additional permissions as appropriate.
202+
203+
It is up to the user provisioning these roles to ensure that this role has only the necessary _read-only_ permissions required to manage infrastructure changes relevant to the delegated repository.
204+
205+
:::
206+
207+
#### `delegated-pipelines-apply`
208+
209+
A read/write apply role for delegated repositories.
210+
211+
- Similar to the plan role, these roles are pre-configured with minimal permissions and are intended for managing OpenTofu/Terraform state.
212+
- A pull request will be opened in `infrastructure-live-access-control` during provisioning include documentation for adding additional permissions if necessary.
213+
- Users must ensure that the role has only the necessary _read/write_ permissions required for the delegated repository.
214+
215+
:::note
216+
The `delegated-pipelines-plan` and `delegated-pipelines-apply` roles are automatically provisioned for new delegated accounts. Enterprise customers will see pull requests created in the `infrastructure-live-access-control` repository to vend these roles with proper configurations.
217+
:::
218+
219+
## Trust boundaries
220+
221+
A critical aspect of Pipelines' architecture is understanding its trust model. Since Pipelines runs within a CI/CD system, it has privileged access to your infrastructure resources (e.g. AWS accounts, VPCs, EC2 instances, etc.).
222+
223+
Anyone with the ability to edit code in the `main` branch of your repositories inherently has the authority to make corresponding changes in your infrastructure resources. For this reason, it is important to follow the [Repository Access](/2.0/docs/pipelines/installation/viamachineusers#repository-access) guidelines to ensure appropriate access control.
224+
225+
:::tip
226+
227+
Each AWS IAM role provisioned through setup of [Gruntwork Account Factory](https://docs.gruntwork.io/account-factory/overview) is configured to trust a single repository (and, for apply roles, a single branch). If a role's permissions become overly broad, consider creating a new role with more granular permissions tailored to the specific use case. Use the `infrastructure-live-access-control` repository to define and manage these roles.
228+
229+
:::

‎docs/2.0/docs/pipelines/architecture/security-controls.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Controls
22

3-
Gruntwork Pipelines employs a defense-in-depth approach to secure workflows across both GitHub and GitLab platforms. This document outlines the controls Pipelines uses to ensure that only infrastructure written in code and approved by a reviewer can be deployed to your AWS accounts.
3+
Gruntwork Pipelines employs a defense-in-depth approach to secure workflows across both GitHub and GitLab platforms. This document outlines the controls Pipelines uses to ensure that only infrastructure written in code and approved by a reviewer can be deployed to your cloud environments (e.g. AWS accounts).
44

55
## Least privilege principle
66

0 commit comments

Comments
 (0)