Protega

Configuration via Environment Variables

Protega is configured exclusively through environment variables and follows two core principles: The Override Hierarchy and the "WHERE vs. WHAT" model for secrets.

Principle 1: The Override Hierarchy

  1. Tool-Specific (PROTEGA_*): An environment variable is the most specific and will always be used if present.
  2. Universal (3SC_*): If a PROTEGA_* variable is not found, the tool looks for a corresponding 3SC_* variable.
  3. Hard-coded Default: If neither is set, the tool falls back to a safe, built-in default.

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

  • The "WHERE" (The Connection): These variables tell the tool where your secrets vault is and how to authenticate (e.g., 3SC_VAULT_TYPE, PROTEGA_GIT_VAULT_TYPE).
  • The "WHAT" (The Secret Name): These variables tell the tool what specific secret to retrieve (e.g., PROTEGA_GIT_PAT_SECRET_NAME).

The Golden Rule: If you define a "WHERE" for a task, the tool will require you to provide the corresponding "WHAT".

Core CI Configuration

Variable (PROTEGA_*) Fallback (3SC_*) Required? Default Purpose
PROTEGA_LICENSE_SERVER_URL 3SC_LICENSE_SERVER_URL Yes The full URL of the 3SC License Server.
PROTEGA_LICENSE_TIMEOUT_SECONDS 3SC_LICENSE_TIMEOUT_SECONDS No 300 Total time (seconds) to wait for a license.
PROTEGA_LICENSE_RETRY_INTERVAL_SECONDS 3SC_LICENSE_RETRY_INTERVAL_SECONDS No 30 Time (seconds) between license acquisition retries.
PROTEGA_LOG_LEVEL 3SC_LOG_LEVEL No Information The logging level for the tool.

Git & Repository Configuration

Variable (PROTEGA_*) Fallback (3SC_*) Purpose
PROTEGA_GIT_REPO_URL 3SC_GIT_REPO_URL Required for remote clones. The full HTTPS URL of the Git repository.
PROTEGA_GIT_BRANCH 3SC_GIT_BRANCH The specific branch to clone (defaults to remote's default).
PROTEGA_GIT_SUBDIRECTORY 3SC_GIT_SUBDIRECTORY Path to a specific project within a monorepo to scope the analysis.
PROTEGA_FORCE_UNSAFE_GIT_PUSH 3SC_FORCE_UNSAFE_GIT_PUSH Must be true to allow git push from an unknown/local environment.
PROTEGA_GIT_PAT 3SC_GIT_PAT A Personal Access Token provided directly. (Not Recommended)
PROTEGA_GIT_PAT_SECRET_NAME The "WHAT": The name of the secret in a vault that contains the Git PAT.
PROTEGA_GIT_VAULT_TYPE 3SC_VAULT_TYPE The scoped "WHERE": Specifies the vault provider for the Git PAT.
PROTEGA_GIT_VAULT_URL 3SC_VAULT_URL The scoped "WHERE": The endpoint for the vault used for the Git PAT.
PROTEGA_GIT_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID The scoped "WHERE": Azure SP Client ID for the Git PAT vault.
PROTEGA_GIT_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET The scoped "WHERE": Azure SP Client Secret for the Git PAT vault.
PROTEGA_GIT_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID The scoped "WHERE": Azure Tenant ID for the Git PAT vault.
PROTEGA_GIT_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID The scoped "WHERE": AWS Access Key ID for the Git PAT vault.
PROTEGA_GIT_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY The scoped "WHERE": AWS Secret Access Key for the Git PAT vault.
PROTEGA_GIT_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS The scoped "WHERE": Path to the GCP service account key file for the Git PAT vault.
PROTEGA_GIT_VAULT_TOKEN 3SC_VAULT_TOKEN The scoped "WHERE": The HashiCorp Vault token for the Git PAT vault.

Observability Configuration

Variable (PROTEGA_*) Fallback (3SC_*) Purpose
PROTEGA_LOG_ENDPOINT_URL 3SC_LOG_ENDPOINT_URL The URL for the remote logging endpoint.
PROTEGA_LOG_ENDPOINT_TOKEN 3SC_LOG_ENDPOINT_TOKEN A direct authentication token for the endpoint.
PROTEGA_LOG_ENDPOINT_TOKEN_SECRET_NAME The "WHAT": The name of the secret in a vault that contains the token.
PROTEGA_LOG_VAULT_TYPE 3SC_VAULT_TYPE The scoped "WHERE": Specifies the vault provider for the token.
PROTEGA_LOG_VAULT_URL 3SC_VAULT_URL The scoped "WHERE": The endpoint for the vault used for the token.
PROTEGA_LOG_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID The scoped "WHERE": Azure SP Client ID for the token vault.
PROTEGA_LOG_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET The scoped "WHERE": Azure SP Client Secret for the token vault.
PROTEGA_LOG_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID The scoped "WHERE": Azure Tenant ID for the token vault.
PROTEGA_LOG_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID The scoped "WHERE": AWS Access Key ID for the token vault.
PROTEGA_LOG_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY The scoped "WHERE": AWS Secret Access Key for the token vault.
PROTEGA_LOG_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS The scoped "WHERE": Path to the GCP service account key file for the token vault.
PROTEGA_LOG_VAULT_TOKEN 3SC_VAULT_TOKEN The scoped "WHERE": The HashiCorp Vault for the token.

Control Point Configuration

Variable (PROTEGA_*) Fallback (3SC_*) Purpose
PROTEGA_CP_AFTERANALYSIS_URL URL for the webhook invoked after policy validation.
PROTEGA_CP_WEBHOOK_TOKEN A direct authentication token for all Control Point webhooks.
PROTEGA_CP_WEBHOOK_TOKEN_SECRET_NAME The "WHAT": The name of the secret in a vault that contains the token.
PROTEGA_CP_VAULT_TYPE 3SC_VAULT_TYPE The scoped "WHERE": Specifies the vault provider for the token.
PROTEGA_CP_VAULT_URL 3SC_VAULT_URL The scoped "WHERE": The endpoint for the vault used for the token.
PROTEGA_CP_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID The scoped "WHERE": Azure SP Client ID for the token vault.
PROTEGA_CP_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET The scoped "WHERE": Azure SP Client Secret for the token vault.
PROTEGA_CP_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID The scoped "WHERE": Azure Tenant ID for the token vault.
PROTEGA_CP_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID The scoped "WHERE": AWS Access Key ID for the token vault.
PROTEGA_CP_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY The scoped "WHERE": AWS Secret Access Key for the token vault.
PROTEGA_CP_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS The scoped "WHERE": Path to the GCP service account key file for the token vault.
PROTEGA_CP_VAULT_TOKEN 3SC_VAULT_TOKEN The scoped "WHERE": The HashiCorp Vault token for the token.

Licensing & Degraded Mode

If a valid license cannot be acquired, Protega runs in a Degraded Mode. In this mode, it will still perform the full analysis and log a summary of violations to the console. However, it will not generate the protega-data.json report, commit to Git, or return a non-zero exit code, ensuring that licensing issues do not block your pipeline.