Implementing Security Best Practices

1. Using OIDC for Cloud Access

Feature	Description	Notes
OIDC Integration	Enables secure cloud access using OpenID Connect (OIDC) tokens instead of long-lived credentials.	Supports AWS, GCP, Azure, and other cloud providers with OIDC support.
Token Duration	OIDC tokens are valid for up to 1 hour.	Automatic refresh via CircleCI's token exchange mechanism.
Role Assignment	Assigns roles to CircleCI workflows using cloud provider IAM roles.	Requires proper trust policies in cloud identity providers.

Example: Configure OIDC for AWS Access

version: 2.1
jobs:
  deploy:
    machine:
      image: ubuntu-2004:2023.07.1
    steps:
      - checkout
      - run:
          name: Setup AWS CLI with OIDC
          command: |
            # Install AWS CLI v2
            curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
            unzip awscliv2.zip
            sudo ./aws/install
            # Configure AWS CLI to use OIDC
            aws configure set region us-east-1
            aws configure set credential_source Ec2InstanceDocument

Note: OIDC integration requires the cloud provider to support OpenID Connect and proper trust policies for CircleCI's identity.

Warning: Ensure that the IAM role or service account used for OIDC has minimal required permissions to reduce security risks.

2. Configuring IP Ranges

Property	Value	Description
ip_ranges	`["192.168.1.0/24", "10.0.0.0/8"]`	Array of IP ranges to allow access to CircleCI services

Example: Configuring IP Ranges in CircleCI

version: 2.1
orbs:
  circleci-cli: circleci/cli@1.0.0
workflows:
  build:
    jobs:
      - circleci-cli/setup

Note: Ensure that the IP ranges you configure are accurate to avoid blocking legitimate traffic.

Warning: Misconfiguring IP ranges can lead to unauthorized access or denial of service.

3. Using Signed Commits

Commit Type	Description	Verification Status	Notes
GPG Signed	Commits are signed with GPG keys to verify authorship	NEW	Ensures authenticity and integrity of commits
SSH Signed	Commits are signed using SSH keys for verification	DEPRECATED	Legacy method; GPG preferred

Example: Setting up GPG for Signed Commits

gpg --gen-key
git config --global commit.gpgsign true
git config --global gpg.program gpg

Example: Verifying a Signed Commit

git log --show-signature

Note: CircleCI will verify GPG-signed commits if the signing key is available in the repository's trust store or configured via environment variables.

Warning: Ensure GPG keys are securely stored and not exposed in configuration files or logs.

4. Scanning for Vulnerabilities

Scan Type	Description	Configuration	Notes
Dependency Scanning	Scans for vulnerable dependencies in project	`dependencies:` block with `scan` option	Supports npm, pip, maven, gradle
Container Scanning	Scans container images for vulnerabilities	`container:` block with `scan` option	Uses Clair or Trivy under the hood
Secrets Scanning	Scans for exposed secrets in code or config	`secrets:` block with `scan` option	Can be configured to fail builds on secrets found

Example: Dependency Scan Configuration

version: 2.1
jobs:
  scan-dependencies:
    docker:
      - image: circleci/node:18
    steps:
      - checkout
      - run:
          name: Run Dependency Scan
          command: |
            npm install
            npx audit-ci --audit-level high

Example: Container Scan Configuration

version: 2.1
jobs:
  scan-container:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Scan Container Image
          command: |
            docker build -t myapp .
            docker run --rm myapp trivy image myapp

Note: Vulnerability scanning can be integrated into the build pipeline to fail builds when critical vulnerabilities are detected.

5. Implementing SAST

Aspect	Description	Implementation
Static Analysis Tools	Tools that analyze source code without executing it to detect vulnerabilities.	`semgrep`, `sonarqube`, `checkmarx`
Integration in Pipeline	How SAST tools are integrated into CircleCI workflows.	Using `circleci config validate` and custom orbs for scanning.
Scan Configuration	Configuration options to define rules and exclusions.	`rules: - id: "no-hardcoded-credentials" message: "Do not hardcode credentials in code" languages: [javascript, python] severity: ERROR`

Example: SAST Configuration in CircleCI

version: 2.1
orbs:
  sast: circleci/sast@1.0.0

jobs:
  security-scan:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - sast/scan

Note: Ensure SAST tools are configured to scan all relevant code paths and exclude false positives where possible.

6. Implementing DAST

Example: Configuring DAST in CircleCI

version: 2.1
jobs:
  dast-scan:
    docker:
      - image: circleci/python:3.9
    steps:
      - checkout
      - run:
          name: Install DAST tools
          command: |
            pip install owasp-zap-api
      - run:
          name: Run DAST scan
          command: |
            zap-cli start
            zap-cli open "https://example.com"
            zap-cli active-scan "https://example.com"
            zap-cli report -o dast-report.html

Feature	Description	Configuration	Status
DAST scan type	Active scanning of web applications	`zap-cli active-scan`	NEW
Report generation	HTML report of DAST findings	`zap-cli report -o report.html`	NEW

Note: DAST tools like OWASP ZAP can be integrated into CircleCI pipelines to automate security scanning of web applications.

Warning: Ensure DAST scans do not impact production systems or violate compliance policies.

7. Using Container Scanning

Container scanning in CircleCI helps identify vulnerabilities in container images used in builds and deployments. This feature integrates with third-party tools to scan for security issues.

Feature	Description	Availability
container-scanning	Enables scanning of container images for known vulnerabilities.	NEW in CircleCI 2.1

Example: Enabling Container Scanning

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - scan:
          image: circleci/node:16

Note: Container scanning requires integration with a third-party scanner such as Snyk or Twistlock.

Warning: Ensure that the container image being scanned is not exposed to public networks.

Configuration Option	Values	Description
image	`circleci/node:16`	The container image to scan for vulnerabilities.
scanner	`snyk`, `twistlock`	Specifies the scanner to use for vulnerability detection.
fail-build-on-issues	`true`, `false`	Set to `true` to fail the build if vulnerabilities are found.

8. Enabling Audit Logs

Example: Configuring Audit Logs in CircleCI

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - run: npm test

workflows:
  version: 2
  build-and-test:
    jobs:
      - build
    triggers:
      - schedule:
          cron: "0 0 * * *"
          filters:
            branches:
              only:
                - main

Configuration Option	Description	Default Value	Notes
audit_logs.enabled	Enables or disables audit logging	`false`	Set to `true` to enable audit logs
audit_logs.output_path	Path where audit logs are stored	`/var/log/circleci/audit.log`	Can be overridden to custom path

Note: Audit logs capture actions performed within the CircleCI environment, including job runs, configuration changes, and user activities.

Warning: Ensure that audit logs are securely stored and protected from unauthorized access to maintain compliance.

Key Points

Audit logs provide a detailed record of system activities.
Enable audit logs via configuration to track security-relevant events.
Store logs securely and ensure they are not tampered with.

9. Preventing Secret Leakage

Method	Description	Notes
circleci env	`circleci env set SECRET_KEY value`	Set environment variables securely via CLI
circleci config process	`circleci config process .circleci/config.yml`	Validate and process config without running jobs
circleci local execute	`circleci local execute -c .circleci/config.yml --job build`	Test jobs locally to avoid exposing secrets

Example: Using CircleCI Environment Variables

circleci env set DATABASE_URL postgres://user:pass@host:5432/db
circleci env set API_KEY <your-api-key>

Note: Never hardcode secrets in .circleci/config.yml. Always use CircleCI's encrypted environment variables or context features.

Warning: Avoid logging or echoing secret values in job steps. Use set +x to disable echo for sensitive commands.

Best Practices for Secret Management

Use CircleCI contexts to manage shared secrets across projects
Rotate API keys and passwords regularly
Implement secret scanning tools in your pipeline (e.g., trufflehog)
Avoid printing secrets in logs or stdout

10. Configuring Build Forked PRs

Setting	Description	Default	Notes
build_forked_pull_requests	Controls whether CircleCI builds pull requests from forked repositories	`false`	Set to `true` to enable builds for forked PRs

Example: Enabling forked PR builds

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
workflows:
  version: 2
  build-workflow:
    jobs:
      - build
    filters:
      branches:
        ignore: /^(?:gh-pages|release\/.*)$/
      pull_requests:
        build_forked_pull_requests: true

Note: When build_forked_pull_requests is set to true, CircleCI will build forked PRs but with limited access to environment variables and secrets for security reasons.