CodeBuild projects should not have privileged mode enabled

Privileged mode in CodeBuild disables container isolation by granting the build process access to all Linux kernel capabilities and host devices. A compromised build step, malicious dependency, or supply-chain attack within a privileged container can escape to the underlying host, access the instance metadata service without restrictions, and potentially pivot to other resources in the account. Most build workloads do not need this level of access.

The only legitimate use case for privileged_mode is building Docker images inside CodeBuild. If your project doesn't produce container images, it should always be off. Even for Docker builds, consider alternatives like ECR native image actions or a dedicated, tightly scoped project.

Retrofit consideration

Projects that build Docker images inside CodeBuild require privileged mode. Disabling it on those projects will break the build. Audit each project's buildspec before making any changes.

Implementation

Choose the approach that matches how you manage Terraform.

Terraform resources

Use AWS provider resources directly. See docs for the resources involved: aws_codebuild_project.

resource "aws_codebuild_project" "this" {
  artifacts {
    encryption_disabled = false
    location            = "example-bucket-abc123"
    type                = "S3"
  }

  logs_config {
    cloudwatch_logs {
      status = "ENABLED"
    }
  }

  name         = "pofix-abc123"
  service_role = "arn:aws:iam::123456789012:role/example-role"

  source {
    buildspec = "version: 0.2\nphases:\n  build:\n    commands:\n      - echo hello"
    type      = "NO_SOURCE"
  }

  environment {
    compute_type    = "BUILD_GENERAL1_SMALL"
    image           = "aws/codebuild/amazonlinux2-x86_64-standard:5.0"
    privileged_mode = false
    type            = "LINUX_CONTAINER"
  }
}

What this control checks

The environment block in aws_codebuild_project takes a privileged_mode argument. It passes when privileged_mode is false or omitted (the Terraform default is false), and fails when privileged_mode = true. Each project is evaluated independently. For batch build configurations with environment overrides, only the base environment definition is checked.

Common pitfalls

Docker-in-Docker builds will break
"Cannot connect to the Docker daemon" is the error you'll hit when disabling privileged mode on a project that runs docker build. These projects require privileged_mode = true, full stop. Either carve out a documented exception or consolidate Docker builds into a separate, tightly scoped project.
Default value masks intent
Set privileged_mode = false explicitly rather than relying on the Terraform default. Omitting it passes the control, but an explicit setting documents intent in code review and makes it harder to accidentally flip on during a future refactor.
Overrides in StartBuild API calls
This control only checks the project definition. The StartBuild and StartBuildBatch APIs accept a privilegedModeOverride parameter that can enable privileged mode at runtime even when the project definition has it disabled. Block this at the IAM or SCP layer by denying codebuild:StartBuild calls that include privileged overrides.

Audit evidence

AWS Config rule evaluation results showing all aws_codebuild_project resources as COMPLIANT, with privilegedMode set to false in the environment configuration, are the primary evidence. Screenshots or API exports from the CodeBuild console with the "Privileged" checkbox unchecked for each project provide supporting documentation. CloudTrail CreateProject and UpdateProject events confirm no project was recently modified to enable privileged mode. In multi-account environments, aggregate findings across accounts and regions in a centralized compliance view.

Framework-specific interpretation

PCI DSS v4.0: PCI DSS v4.0 Requirement 2.2 says system components must be configured to minimize their attack surface. A CI/CD pipeline connected to a cardholder data environment is in scope, and running build containers with privileged mode is exactly the kind of unnecessary capability Req 2.2 targets. Disabling it limits the blast radius if a build step is compromised.

Lambda functions should use latest runtimes

Tool mappings

Use these identifiers to cross-reference this control across tools, reports, and evidence.

Compliance.tf Control: codebuild_project_environment_privileged_mode_disabled
AWS Config Managed Rule: CODEBUILD_PROJECT_ENVIRONMENT_PRIVILEGED_CHECK
Checkov Check: CKV_AWS_316
Powerpipe Control: aws_compliance.control.codebuild_project_environment_privileged_mode_disabled

Last reviewed: 2026-03-09