Vestigo

Configuration via Environment Variables

Vestigo 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 (VESTIGO_*): An environment variable starting with VESTIGO_ is the most specific and will always be used if present.
  2. Universal (3SC_*): If a VESTIGO_* 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 is the most critical concept for configuring secrets. It 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. They are the connection details (URL, credentials, etc.). You can define a global "WHERE" using 3SC_VAULT_* variables, and then override it for a specific task (like Git) using VESTIGO_GIT_VAULT_* variables.

  • The "WHAT" (The Secret Name): These variables tell the tool what specific secret to retrieve from the vault. For example, VESTIGO_GIT_PAT_SECRET_NAME tells the tool to ask the vault for the secret that holds the Git Personal Access Token. The "WHAT" is always tool-specific because the secret for a Git PAT is different from the secret for a logging 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".

The Universal "WHERE": Global Vault Configuration

These 3SC_* variables define the default vault connection for all tools. A tool-specific scope (like Git) will use these values unless explicitly overridden.

Variable Required? Purpose
3SC_VAULT_TYPE No The Global "WHERE": The default secrets vault provider. Supported: Azure, AWS, GCP, HashiCorp.
3SC_VAULT_URL Conditional The Global "WHERE": The endpoint URL for the secrets vault (for Azure Key Vault and HashiCorp Vault).
3SC_AZURE_CLIENT_ID Conditional The Global "WHERE": The Client ID for Azure service principal authentication.
3SC_AZURE_CLIENT_SECRET Conditional The Global "WHERE": The Client Secret for Azure service principal authentication.
3SC_AZURE_TENANT_ID Conditional The Global "WHERE": The Tenant ID for the Azure service principal.
3SC_AWS_ACCESS_KEY_ID Conditional The Global "WHERE": The Access Key ID for AWS authentication.
3SC_AWS_SECRET_ACCESS_KEY Conditional The Global "WHERE": The Secret Access Key for AWS authentication.
GOOGLE_APPLICATION_CREDENTIALS Conditional The Global "WHERE": Path to the JSON file with Google Cloud credentials.
3SC_VAULT_TOKEN Conditional The Global "WHERE": The authentication token for HashiCorp Vault.

Core CI & Gating Configuration

These variables control the primary execution and decision-making logic of the tool.

Variable (VESTIGO_*) Fallback (3SC_*) Required? Default Purpose
VESTIGO_LICENSE_SERVER_URL 3SC_LICENSE_SERVER_URL Yes The full URL of the 3SC License Server.
VESTIGO_LICENSE_TIMEOUT_SECONDS 3SC_LICENSE_TIMEOUT_SECONDS No 300 Timeout in seconds for license server requests.
VESTIGO_LICENSE_RETRY_INTERVAL_SECONDS 3SC_LICENSE_RETRY_INTERVAL_SECONDS No 30 Time in seconds to wait between license retry attempts.
VESTIGO_ALERT_THRESHOLD No 2 If a module's risk ranking moves up by this many positions, trigger an Alert (exit code 70).
VESTIGO_FAIL_THRESHOLD No 5 If a module's risk ranking moves up by this many positions, trigger a Fail (exit code 71).
VESTIGO_ALERT_ON_NEW_ENTRIES No true If a new module enters the risk rankings for the first time, trigger an Alert.
VESTIGO_MINIMUM_PERCENTILE No 70 The percentile cutoff for a module to be considered a risk hotspot.
VESTIGO_EXCLUDED_AREAS No A semicolon-separated list of directory paths to exclude from analysis (e.g., src/legacy/;tests/).
VESTIGO_FETCH_DEPTH No Limits the git clone and log history to the specified number of recent commits.
VESTIGO_LOG_LEVEL 3SC_LOG_LEVEL No Information The logging level for the tool.

Git & Repository Configuration

These variables define the repository Vestigo will analyze.

Note on CI Environments: The tool automatically discovers the local workspace path from common CI environment variables (GITHUB_WORKSPACE, CI_PROJECT_DIR, BUILD_SOURCESDIRECTORY). The _GIT_REPO_URL variables are only required if you need the tool to perform a remote git clone from a clean environment.

Variable (VESTIGO_*) Fallback (3SC_*) Required? Purpose
VESTIGO_GIT_REPO_URL 3SC_GIT_REPO_URL Conditional¹ The full HTTPS URL of the Git repository for remote clones.
VESTIGO_GIT_BRANCH 3SC_GIT_BRANCH Conditional¹ The specific branch to clone and commit to.
VESTIGO_GIT_SUBDIRECTORY 3SC_GIT_SUBDIRECTORY No Path to a specific project within a monorepo to scope the analysis.
VESTIGO_FORCE_UNSAFE_GIT_PUSH 3SC_FORCE_UNSAFE_GIT_PUSH No Must be set to true to allow git push from an unsafe CI environment.
VESTIGO_GIT_PAT 3SC_GIT_PAT Conditional² A Personal Access Token provided directly. (Not Recommended)
VESTIGO_GIT_PAT_SECRET_NAME Conditional³ The "WHAT": The name of the secret in a vault that contains the Git PAT.
VESTIGO_GIT_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Git operations only.
VESTIGO_GIT_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": Overrides the Vault endpoint for Git operations only.
VESTIGO_GIT_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Overrides the Azure Client ID for Git operations only.
VESTIGO_GIT_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Overrides the Azure Client Secret for Git operations only.
VESTIGO_GIT_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Overrides the Azure Tenant ID for Git operations only.
VESTIGO_GIT_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": Overrides the AWS Access Key for Git operations only.
VESTIGO_GIT_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": Overrides the AWS Secret Key for Git operations only.
VESTIGO_GIT_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Overrides the GCP credentials for Git operations only.
VESTIGO_GIT_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": Overrides the HashiCorp token for Git operations only.

¹ Required only if the tool needs to perform a remote git clone. ² Required if not using a Vault-based PAT. ³ Required if VESTIGO_GIT_VAULT_TYPE or 3SC_VAULT_TYPE is set.

Observability (Firehose) Configuration

These variables control sending the analysis summary to a remote logging endpoint. This feature is disabled if _URL is not set.

Variable (VESTIGO_*) Fallback (3SC_*) Required? Purpose
VESTIGO_LOG_ENDPOINT_URL 3SC_LOG_ENDPOINT_URL No The URL for the Firehose endpoint.
VESTIGO_LOG_ENDPOINT_TOKEN 3SC_LOG_ENDPOINT_TOKEN Conditional¹ A direct authentication token for the endpoint.
VESTIGO_LOG_ENDPOINT_TOKEN_SECRET_NAME Conditional² The "WHAT": The name of the secret in a vault that contains the token.
VESTIGO_LOG_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Logging operations only.
VESTIGO_LOG_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": Overrides the Vault endpoint for Logging operations only.
VESTIGO_LOG_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Overrides the Azure Client ID for Logging operations only.
VESTIGO_LOG_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Overrides the Azure Client Secret for Logging operations only.
VESTIGO_LOG_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Overrides the Azure Tenant ID for Logging operations only.
VESTIGO_LOG_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": Overrides the AWS Access Key for Logging operations only.
VESTIGO_LOG_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": Overrides the AWS Secret Key for Logging operations only.
VESTIGO_LOG_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Overrides the GCP credentials for Logging operations only.
VESTIGO_LOG_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": Overrides the HashiCorp token for Logging operations only.

¹ Required if VESTIGO_LOG_ENDPOINT_URL is set and not using a Vault. ² Required if VESTIGO_LOG_ENDPOINT_URL is set and (VESTIGO_LOG_VAULT_TYPE or 3SC_VAULT_TYPE) is set.

Control Point Configuration

These variables configure authenticated webhooks for pipeline integration. This feature is disabled if no _URL variables are set.

Variable (VESTIGO_*) Fallback (3SC_*) Required? Purpose
VESTIGO_CP_GITANALYSIS_AFTER_URL No URL for the webhook invoked after Git analysis.
VESTIGO_CP_RISKANALYSIS_AFTER_URL No URL for the webhook invoked after risk calculation.
VESTIGO_CP_DECISION_BEFORE_URL No URL for the webhook invoked before the final decision.
VESTIGO_CP_WEBHOOK_TOKEN Conditional¹ A direct authentication token for all Control Point webhooks.
VESTIGO_CP_WEBHOOK_TOKEN_SECRET_NAME Conditional² The "WHAT": The name of the secret in a vault that contains the token.
VESTIGO_CP_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Control Point operations only.
VESTIGO_CP_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": Overrides the Vault endpoint for Control Point operations only.
VESTIGO_CP_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Overrides the Azure Client ID for Control Point operations only.
VESTIGO_CP_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Overrides the Azure Client Secret for Control Point operations only.
VESTIGO_CP_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Overrides the Azure Tenant ID for Control Point operations only.
VESTIGO_CP_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": Overrides the AWS Access Key for Control Point operations only.
VESTIGO_CP_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": Overrides the AWS Secret Key for Control Point operations only.
VESTIGO_CP_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Overrides the GCP credentials for Control Point operations only.
VESTIGO_CP_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": Overrides the HashiCorp token for Control Point operations only.

¹ Required if any _URL is set and not using a Vault. ² Required if any _URL is set and (VESTIGO_CP_VAULT_TYPE or 3SC_VAULT_TYPE) is set.

Overriding CI Gates

In certain situations, such as a known-good refactoring that temporarily increases churn or during an emergency hotfix, you may need to bypass Vestigo's risk gate. Vestigo provides a safe, one-time override mechanism for this purpose.

  • How it works: Create an empty file named .vestigo-force-pass in the root of your repository (or the subdirectory being scanned).
  • What it does: When the execute command runs and detects this file, it will:
    1. Perform the full risk analysis as usual.
    2. Log a warning that the override file was detected.
    3. Force the final exit code to 0 (Pass), regardless of the actual Alert or Fail decision.
    4. Crucially, it will delete the .vestigo-force-pass file as part of its artifact commit.

This self-deleting mechanism ensures that the override is for a single run only, preventing it from being accidentally left in place and permanently disabling the risk gate.

Licensing & Degraded Mode

  • If a valid license cannot be acquired in execute mode, Vestigo runs in a Degraded Mode.
  • In this mode, it performs the full analysis and logs its findings to the console, but it will always return exit code 0 (Pass), effectively making the risk gate an informational-only check.