Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• core/configuration.py
• config/overlay.demo.yml
• config/overlay.enterprise.yml
• core/cli.py
• core/overlay_runtime.py
• config/policy.yml

The Aldeci application utilizes a flexible and layered configuration system driven by YAML "overlay" files. This system allows the application to operate in different modes, such as demo or enterprise, by merging a base configuration with mode-specific settings. The configuration is loaded at startup and can be further customized with environment variables, providing a high degree of control over the application's behavior, from feature toggles to security policies.

The core of this system is the load_overlay function, which parses these YAML files, validates their structure, and constructs an OverlayConfig object. This object serves as the single source of truth for configuration throughout the application's lifecycle. The system is designed to be secure, preventing path traversal and ensuring that all file paths specified in configurations are within designated, secure directories.

Configuration Loading Flow

The application loads its configuration through a multi-step process that starts from a command-line argument, merges multiple YAML files, and applies environment-specific overrides.

This diagram illustrates the configuration loading and preparation sequence.

1. Initiation: A user runs the application via the CLI, specifying an overlay profile, for example: ... run --overlay demo.
   Sources: core/cli.py:440-441
2. Environment Overrides: The _apply_env_overrides function in the CLI module scans for environment variables prefixed with FIXOPS_ and applies them over any file-based settings.
   Sources: core/cli.py:46-51
3. Overlay Loading: The load_overlay function from core/configuration.py is called. It reads the specified YAML file (e.g., config/overlay.demo.yml).
   Sources: core/configuration.py:238
4. Merging: The loaded overlay configuration is deeply merged with any base configurations it extends. For example, the demo overlay extends the base policy.yml.
   Sources: core/configuration.py:100-104, config/overlay.demo.yml:1-2
5. Validation: A series of validation functions (_validate_policy_config, _validate_compliance_config, etc.) are run to ensure the configuration structure is correct and all required fields are present.
   Sources: core/configuration.py:125-220
6. Object Creation: An immutable OverlayConfig object is instantiated with the validated and merged configuration data.
   Sources: core/configuration.py:84
7. Runtime Preparation: The prepare_overlay function from core/overlay_runtime.py is called with the OverlayConfig object. This function performs runtime setup tasks, such as creating necessary directories (limits.evidence.root) and checking for the presence of required secrets for enabled automation connectors.
   Sources: core/overlay_runtime.py:20-63

Overlay Configuration Structure

The configuration is structured into several key sections within the YAML files, each controlling a different aspect of the application. The OverlayConfig class models this structure.

This class diagram shows the main components of the OverlayConfig object.

Key Configuration Sections

Section	Description	Example File
extends	Specifies a path to a base YAML file to inherit from. Settings in the current file will override the base.	config/overlay.demo.yml
policy	Defines security and operational policies, including the policy engine to use (e.g., OPA), its configuration, and specific policy rules.	config/policy.yml
compliance	Configures compliance frameworks and controls that the application should evaluate against.	config/overlay.enterprise.yml
modules	A set of boolean flags to enable or disable specific features or processing modules within the pipeline.	config/overlay.demo.yml
limits	Sets operational limits, such as evidence bundle size, encryption settings, and allow-listed directories for file operations.	config/overlay.enterprise.yml
signing	Configures artifact signing, including the provider (e.g., local, kms), key fingerprints, and rotation policies.	config/overlay.enterprise.yml
automation	Defines connection details and credentials for external systems like Jira, Confluence, and Slack for automated ticket creation or notifications.	config/overlay.enterprise.yml
ai	Configures providers and models for AI-based features, such as the enhanced decision engine.	config/overlay.enterprise.yml
pricing	Contains settings related to feature pricing and plans, used for calculating ROI and in tenancy modules.	config/overlay.enterprise.yml

Sources: core/configuration.py:84-96, config/overlay.demo.yml, config/overlay.enterprise.yml, config/policy.yml

Example: Demo Overlay

The demo overlay is a minimal configuration designed for demonstration purposes. It enables a subset of modules and uses local signing.

# config/overlay.demo.yml
extends: ./policy.yml

modules:
  # Core context and guardrails
  context_engine: true
  guardrails: true

  # SSDLC stages
  ssdlc: true
  iac: true

  # Advanced analytics
  exploit_signals: true
  ai_agents: false
  probabilistic: false

# ... more settings

Sources: config/overlay.demo.yml:1-17

Example: Enterprise Overlay

The enterprise overlay demonstrates a more complex setup, enabling advanced features like compliance packs, policy automation, and cloud-based key management for signing.

# config/overlay.enterprise.yml
extends: ./policy.yml

modules:
  # Enable everything for enterprise demos
  context_engine: true
  guardrails: true
  ssdlc: true
  iac: true
  exploit_signals: true
  ai_agents: true
  probabilistic: true
  compliance: true
  policy_automation: true
  # ... more modules

signing:
  # Example using AWS KMS
  provider: kms
  key_id: "alias/fixops-signing-key"
  # ... more settings

automation:
  connectors:
    jira:
      url: "https://my-jira.example.com"
      token_env: "JIRA_TOKEN"
    # ... more connectors

Sources: config/overlay.enterprise.yml:1-55

Validation and Security

The configuration system includes robust validation to ensure correctness and security.

Structural Validation

During the loading process, helper functions like _validate_policy_config and _validate_compliance_controls check that the configuration dictionaries contain the expected keys and that values have the correct types (e.g., string, list of strings). If an unknown key is found, the application will raise an error, preventing misconfigurations.
Sources: core/configuration.py:150-205

Path Security

To prevent path traversal attacks, any file path read from a configuration file (such as the data_root for evidence bundles) is validated. The _ensure_within_allowlist function ensures that the resolved absolute path is a sub-path of a securely defined and allow-listed root directory. This is a critical security control.
Sources: core/configuration.py:222-236

Runtime Preparation

After the OverlayConfig object is successfully created, the prepare_overlay function in core/overlay_runtime.py prepares the application's runtime environment. Its key responsibilities include:

• Directory Creation: It ensures that the root directories specified in limits.evidence.root and limits.cache.root exist, creating them if necessary.
• Secret Validation: It checks for the presence of environment variables containing tokens or secrets required by enabled automation connectors (e.g., JIRA_TOKEN). If a connector is enabled but its corresponding secret is missing, a runtime warning is logged.
• Encryption Check: It verifies if evidence encryption is requested (limits.evidence.encrypt: true) and checks for the presence of the FERNET_KEY environment variable, disabling encryption with a warning if the key is not found.

Sources: core/overlay_runtime.py:20-63