Skip to content

Improve AWS Pod Identity / IRSA Docs #3314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Weltraumschaf merged 4 commits into from
Oct 14, 2025
Merged

Improve AWS Pod Identity / IRSA Docs #3314

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
afae852
Improve AWS Pod Identity / IRSA docs
J12934 Oct 8, 2025
52df2cf
Rename aws authType for better clarity w/ Pod Identity support
J12934 Oct 14, 2025
0736674
Update wording and styling to hopefully be more clear
J12934 Oct 14, 2025
9e1b152
Fix helm template
J12934 Oct 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 191 additions & 5 deletions documentation/docs/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,11 +79,197 @@ s3:
```

:::info
Instead of using access keys it is possible to use **IAM roles** for more fine grained access management. To achieve that set in your helm values

1. `s3.authType` to `aws-irsa`, and
2. `s3.awsStsEndpoint` to your desired region (`https://sts.REGION.amazonaws.com`).
:::
Instead of using access keys, it is possible to use [EKS Pod Identities](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) or [IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) in secureCodeBox to authenticate to the S3 bucket using short-lived, automatically rotated credentials.

However, because these credentials are short-lived (maximum lifetime of 12 hours), scans started by the operator in this setup are limited in their maximum duration. The tokens are rotated when they reach 20% of their maximum lifetime. If a scan is started at this point, S3 access will this particular scan will work for at most the remaining token duration, which is approximately 2.4 hours. If the scan exceeds this point it will fail after the scan itself is done as it is unable to persist its results.
Comment thread
J12934 marked this conversation as resolved.
Outdated

Depending on the expected scan duration in your setup, this limitation can pose a problem. See: [Issue secureCodeBox/secureCodeBox#2255](https://github.com/secureCodeBox/secureCodeBox/issues/2255)

<details>
<summary>Example Pod Identity Setup (recommended over IRSA)</summary>

Terraform/OpenTofu setup for the IAM Role & Policy:
```tf
resource "aws_iam_policy" "securecodebox_s3_policy" {
name = "securecodebox-s3-${var.bucket_name}-access"
description = "IAM policy for secureCodeBox to access S3 bucket ${var.bucket_name}"

policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Action = [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:GetObjectVersion",
"s3:PutObjectAcl",
"s3:GetObjectAcl"
]
Resource = [
"arn:aws:s3:::${var.bucket_name}/*"
]
},
{
Effect = "Allow"
Action = [
"s3:ListBucket",
"s3:GetBucketLocation",
"s3:GetBucketVersioning"
]
Resource = [
"arn:aws:s3:::${var.bucket_name}"
]
}
]
})
}

# IAM Role for secureCodeBox with EKS Pod Identity
resource "aws_iam_role" "securecodebox_role" {
name = "securecodebox-role"

max_session_duration = 12 * 60 * 60 // 12h, session duration needs to be this long to allow the operator to create presigned urls with a longer lifetime

# Use EKS Pod Identity for the operator service account.
assume_role_policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Principal = {
Service = "pods.eks.amazonaws.com"
}
Action = [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
})
}

# Attach the S3 policy to the role
resource "aws_iam_role_policy_attachment" "securecodebox_s3_policy_attachment" {
role = aws_iam_role.securecodebox_role.name
policy_arn = aws_iam_policy.securecodebox_s3_policy.arn
}

# Create EKS Pod Identity Association
resource "aws_eks_pod_identity_association" "securecodebox_operator" {
cluster_name = var.cluster_name
namespace = "securecodebox-system"
service_account = "securecodebox-operator"
role_arn = aws_iam_role.securecodebox_role.arn
}
```

secureCodeBox Operator values:

```yaml
minio:
enabled: false
s3:
enabled: true
authType: "aws-irsa" # Note: secureCodeBox still uses this config name even for Pod Identity
Comment thread
J12934 marked this conversation as resolved.
Outdated
bucket: <your-bucket-name>
endpoint: "s3.<your-region>.amazonaws.com"
```
</details>

<details>
<summary>Example IRSA Setup</summary>

Terraform/OpenTofu setup for the IAM Role & Policy:
```tf
resource "aws_iam_policy" "securecodebox_s3_policy" {
name = "securecodebox-s3-${var.bucket_name}-access"
description = "IAM policy for secureCodeBox to access S3 bucket ${var.bucket_name}"

policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Action = [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:GetObjectVersion",
"s3:PutObjectAcl",
"s3:GetObjectAcl"
]
Resource = [
"arn:aws:s3:::${var.bucket_name}/*"
]
},
{
Effect = "Allow"
Action = [
"s3:ListBucket",
"s3:GetBucketLocation",
"s3:GetBucketVersioning"
]
Resource = [
"arn:aws:s3:::${var.bucket_name}"
]
}
]
})
}

# IAM Role for secureCodeBox with EKS Pod Identity
resource "aws_iam_role" "securecodebox_role" {
name = "securecodebox-role"

max_session_duration = 12 * 60 * 60 // 12h, session duration needs to be this long to allow the operator to create presigned urls with a longer lifetime

# Use IRSA (IAM Roles for Service Accounts) via the cluster OIDC provider.
# The cluster OIDC issuer is available from the data.aws_eks_cluster.cluster data source.
# The Federated principal is the cluster's OIDC provider ARN in the account.
assume_role_policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Principal = {
Federated = "arn:aws:iam::${var.aws_account_id}:oidc-provider/${var.oidc_provider}"
}
Action = "sts:AssumeRoleWithWebIdentity"
Condition = {
StringEquals = {
"${var.oidc_provider}:sub" = "system:serviceaccount:securecodebox-system:securecodebox-operator"
}
}
}
]
})
}

# Attach the S3 policy to the role
resource "aws_iam_role_policy_attachment" "securecodebox_s3_policy_attachment" {
role = aws_iam_role.securecodebox_role.name
policy_arn = aws_iam_policy.securecodebox_s3_policy.arn
}
```

secureCodeBox Operator values:

```yaml
minio:
enabled: false
s3:
enabled: true
authType: "aws-irsa"
bucket: <your-bucket-name>
endpoint: "s3.<your-region>.amazonaws.com"
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: <ARN of the IAM Role created by terraform>
```
</details>
:::

#### Google Cloud Storage

Expand Down
Loading