Atlas

Configuration via Environment Variables

Atlas is configured exclusively through environment variables. To configure it correctly, it is essential to understand two core principles: The Override Hierarchy and the "WHERE vs. WHAT" model for secrets.

Principle 1: The Override Hierarchy

The system uses a simple, predictable override protocol. For any given setting, the tool looks for variables in this order:

  1. Tool-Specific (ATLAS_*): An environment variable starting with ATLAS_ is the most specific and will always be used if present.
  2. Universal (3SC_*): If an ATLAS_* variable is not found, the tool looks for a corresponding 3SC_* variable. This allows you to define a default behavior for all 3SC tools.
  3. Hard-coded Default: If neither of the above is set, the tool falls back to a safe, built-in default value.

Principle 2: "WHERE vs. WHAT" for Secrets Management

This concept separates the connection to a vault from the secret being requested.

  • The "WHERE" (The Connection): These variables tell the tool where your secrets vault is and how to authenticate. You can define a global "WHERE" using 3SC_VAULT_* variables, and then override it for a specific task (like Git) using ATLAS_GIT_VAULT_* variables.

  • The "WHAT" (The Secret Name): These variables tell the tool what specific secret to retrieve from the vault. For example, ATLAS_GIT_PAT_SECRET_NAME tells the tool to ask the vault for the secret that holds the Git Personal Access Token.

The Golden Rule: If you define a "WHERE" for a task (either globally or with a scope-specific override), the tool will require you to provide the corresponding "WHAT".

Core Configuration

These are the essential variables to run Atlas.

Variable Fallback (3SC_*) Required? Purpose Example
ATLAS_PROVIDER N/A Yes Specifies the cloud provider or service to scan. azure, aws, gcp, kubernetes
ATLAS_LICENSE_SERVER_URL 3SC_LICENSE_SERVER_URL Yes The full URL of the 3SC License Server. https://license.my-company.com
ATLAS_LICENSE_TIMEOUT_SECONDS 3SC_LICENSE_TIMEOUT_SECONDS No Timeout in seconds for license server requests. 300
ATLAS_LICENSE_RETRY_INTERVAL_SECONDS 3SC_LICENSE_RETRY_INTERVAL_SECONDS No Time in seconds to wait between license retry attempts. 15

Provider-Specific Configuration (Authentication & Scope)

These variables are conditional and required based on the value of ATLAS_PROVIDER. Authentication is handled via standard, industry-accepted environment variables for each cloud provider's SDK.

For ATLAS_PROVIDER=azure
Variable Required? Purpose
AZURE_SUBSCRIPTION_ID Yes The ID of the Azure Subscription to scan.
AZURE_CLIENT_ID Yes The Application (client) ID of the Service Principal.
AZURE_CLIENT_SECRET Yes The client secret for the Service Principal.
AZURE_TENANT_ID Yes The Directory (tenant) ID where the Service Principal was created.
For ATLAS_PROVIDER=aws
Variable Required? Purpose
AWS_ACCESS_KEY_ID Yes The Access Key ID for your IAM user.
AWS_SECRET_ACCESS_KEY Yes The Secret Access Key for your IAM user.
AWS_REGION Yes The default AWS Region to begin the scan in (e.g., us-east-1).
For ATLAS_PROVIDER=gcp
Variable Required? Purpose
GCP_ORGANIZATION Yes The name of the GCP Organization to scan (e.g., organizations/123456789012).
GOOGLE_PROJECT_ID Yes The ID of a GCP Project within the organization.
GOOGLE_APPLICATION_CREDENTIALS Yes The file path inside the container to the JSON service account key file.
For ATLAS_PROVIDER=kubernetes

By default, Atlas uses in-cluster authentication. For scanning an external cluster, mount a kubeconfig file and set the KUBECONFIG environment variable.

Sovereign Cloud Support

Optional overrides for air-gapped or sovereign cloud environments.

Variable Required? Description Example
ATLAS_AWS_ENDPOINT_OVERRIDE No Overrides the base URL for all AWS SDK clients (EC2, RDS, CloudWatch). https://api.compute.eu-sovereign-1.aws
ATLAS_AZURE_ENDPOINT_OVERRIDE No Overrides the Azure Resource Manager base URL. https://management.usgovcloudapi.net
ATLAS_GCP_ENDPOINT_OVERRIDE No Overrides the base URL for GCP Asset and Metric clients. https://private-asset.googleapis.com

Git Configuration

Variable (ATLAS_*) Fallback (3SC_*) Required? Purpose
ATLAS_GIT_REPO_URL 3SC_GIT_REPO_URL Yes¹ The full HTTPS URL of the Git repository for storing state.
ATLAS_GIT_BRANCH 3SC_GIT_BRANCH No The specific branch to commit to. Defaults to the remote's default.
ATLAS_GIT_SUBDIRECTORY 3SC_GIT_SUBDIRECTORY No Path within the repo to store artifacts (e.g., infrastructure/atlas).
ATLAS_FORCE_UNSAFE_GIT_PUSH 3SC_FORCE_UNSAFE_GIT_PUSH No Must be true to allow git push from an unsafe CI environment.
ATLAS_GIT_PAT 3SC_GIT_PAT Conditional² A Personal Access Token provided directly. (Not Recommended)
ATLAS_GIT_PAT_SECRET_NAME Conditional³ The "WHAT": The name of the secret in a vault for the Git PAT.
ATLAS_GIT_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Git operations only.
ATLAS_GIT_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": The endpoint for the vault used for the Git PAT.
ATLAS_GIT_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Azure SP Client ID for the Git PAT vault.
ATLAS_GIT_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Azure SP Client Secret for the Git PAT vault.
ATLAS_GIT_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Azure Tenant ID for the Git PAT vault.
ATLAS_GIT_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": AWS Access Key ID for the Git PAT vault.
ATLAS_GIT_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": AWS Secret Access Key for the Git PAT vault.
ATLAS_GIT_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Path to GCP service account key file for the Git PAT vault.
ATLAS_GIT_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": The HashiCorp Vault token for the Git PAT vault.

¹ Required for execute mode. ² Required for private repositories if not using a Vault. ³ Required for private repositories if ATLAS_GIT_VAULT_TYPE or 3SC_VAULT_TYPE is set.

Observability (Firehose) Configuration

Variable (ATLAS_*) Fallback (3SC_*) Required? Purpose
ATLAS_LOG_ENDPOINT_URL 3SC_LOG_ENDPOINT_URL No The URL for the Firehose endpoint. Feature disabled if not set.
ATLAS_LOG_ENDPOINT_TOKEN 3SC_LOG_ENDPOINT_TOKEN Conditional¹ A direct authentication token for the endpoint.
ATLAS_LOG_ENDPOINT_TOKEN_SECRET_NAME Conditional² The "WHAT": The name of the secret in a vault for the token.
ATLAS_LOG_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Logging operations only.
ATLAS_LOG_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": The endpoint for the vault used for the Firehose token.
ATLAS_LOG_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Azure SP Client ID for the Firehose token vault.
ATLAS_LOG_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Azure SP Client Secret for the Firehose token vault.
ATLAS_LOG_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Azure Tenant ID for the Firehose token vault.
ATLAS_LOG_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": AWS Access Key ID for the Firehose token vault.
ATLAS_LOG_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": AWS Secret Access Key for the Firehose token vault.
ATLAS_LOG_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Path to GCP service account key file for the Firehose token vault.
ATLAS_LOG_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": The HashiCorp Vault token for the Firehose token vault.

¹ Required if URL is set and not using a Vault. ² Required if URL is set and a Vault (ATLAS_LOG_VAULT_TYPE or 3SC_VAULT_TYPE) is configured.

Licensing & Degraded Mode

  • If a valid license cannot be acquired, Atlas runs in a Degraded Mode.
  • In this mode, it will still perform the discovery but will not generate the atlas-stats.json or atlas-results.json files, nor will it commit to Git.
  • Instead, it will log a summary of resource counts by type to the console.