FEAT: PyRIT Config

.pyrit_conf_example

@@ -0,0 +1,78 @@
+# PyRIT Configuration File Example
+# ================================
+# This is a YAML-formatted configuration file. Copy to ~/.pyrit/.pyrit_conf
+# or specify a custom path when loading via --config-file.
+#
+# For documentation on configuration options, see:
+# https://github.com/Azure/PyRIT/blob/main/doc/setup/configuration.md
+
+# Memory Database Type
+# --------------------
+# Specifies which database backend to use for storing prompts and results.
+# Options: in_memory, sqlite, azure_sql (case-insensitive)
+# - in_memory: Temporary in-memory database (data lost on exit)
+# - sqlite: Persistent local SQLite database (default)
+# - azure_sql: Azure SQL database (requires connection string in env vars)
+memory_db_type: sqlite
+
+# Initializers
+# ------------
+# List of built-in initializers to run during PyRIT initialization.
+# Initializers configure default values for converters, scorers, and targets.
+# Names are normalized to snake_case (e.g., "SimpleInitializer" -> "simple").
+#
+# Available initializers:
+# - simple: Basic OpenAI configuration (requires OPENAI_CHAT_* env vars)
+# - airt: AI Red Team setup with Azure OpenAI (requires AZURE_OPENAI_* env vars)
+# - load_default_datasets: Loads default datasets for all registered scenarios
+# - objective_list: Sets default objectives for scenarios
+# - openai_objective_target: Sets up OpenAI target for scenarios
+#
+# Each initializer can be specified as:
+# - A simple string (name only)
+# - A dictionary with 'name' and optional 'args' for constructor arguments
+#
+# Example:
+# initializers:
+#   - simple
+#   - name: airt
+#     args:
+#       some_param: value
+initializers:
+  - simple
+
+# Initialization Scripts
+# ----------------------
+# List of paths to custom Python scripts containing PyRITInitializer subclasses.
+# Paths can be absolute or relative to the current working directory.
+#
+# Behavior:
+# - Omit this field (or set to null): No custom scripts loaded (default)
+# - Set to []: Explicitly load no scripts (same as omitting)
+# - Set to list of paths: Load the specified scripts
+#
+# Example:
+# initialization_scripts:
+#   - /path/to/my_custom_initializer.py
+#   - ./local_initializer.py
+
+# Environment Files
+# -----------------
+# List of .env file paths to load during initialization.
+# Later files override values from earlier files.
+#
+# Behavior:
+# - Omit this field (or set to null): Load default .env and .env.local from ~/.pyrit/ if they exist
+# - Set to []: Explicitly load NO environment files
+# - Set to list of paths: Load only the specified files
+#
+# Example:
+# env_files:
+#   - /path/to/.env
+#   - /path/to/.env.local
+
+# Silent Mode
+# -----------
+# If true, suppresses print statements during initialization.
+# Useful for non-interactive environments or when embedding PyRIT in other tools.
+silent: false

pyrit/cli/frontend_core.py

@@ -21,6 +21,9 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Optional, Sequence
 
+from pyrit.setup import ConfigurationLoader
+from pyrit.setup.configuration_loader import _MEMORY_DB_TYPE_MAP
+
 try:
     import termcolor
 
@@ -66,39 +69,74 @@ class FrontendCore:
     def __init__(
         self,
         *,
-        database: str = SQLITE,
+        config_file: Optional[Path] = None,
+        database: Optional[str] = None,
         initialization_scripts: Optional[list[Path]] = None,
         initializer_names: Optional[list[str]] = None,
         env_files: Optional[list[Path]] = None,
-        log_level: str = "WARNING",
+        log_level: Optional[int] = None,
     ):
         """
         Initialize PyRIT context.
 
+        Configuration is loaded in the following order (later values override earlier):
+        1. Default config file (~/.pyrit/.pyrit_conf) if it exists
+        2. Explicit config_file argument if provided
+        3. Individual CLI arguments (database, initializers, etc.)
+
         Args:
+            config_file: Optional path to a YAML-formatted configuration file.
+                The file uses .pyrit_conf extension but is YAML format.
             database: Database type (InMemory, SQLite, or AzureSQL).
             initialization_scripts: Optional list of initialization script paths.
             initializer_names: Optional list of built-in initializer names to run.
             env_files: Optional list of environment file paths to load in order.
-            log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Defaults to WARNING.
+            log_level: Logging level constant (e.g., logging.WARNING). Defaults to logging.WARNING.
 
         Raises:
-            ValueError: If database or log_level are invalid.
+            ValueError: If database is invalid, or if config file is invalid.
+            FileNotFoundError: If an explicitly specified config_file does not exist.
         """
-        # Validate inputs
-        self._database = validate_database(database=database)
-        self._initialization_scripts = initialization_scripts
-        self._initializer_names = initializer_names
-        self._env_files = env_files
-        self._log_level = validate_log_level(log_level=log_level)
+        # Use provided log level or default to WARNING
+        self._log_level = log_level if log_level is not None else logging.WARNING
+
+        # Load configuration using ConfigurationLoader.load_with_overrides
+        try:
+            config = ConfigurationLoader.load_with_overrides(
+                config_file=config_file,
+                memory_db_type=database,
+                initializers=initializer_names,
+                initialization_scripts=[str(p) for p in initialization_scripts] if initialization_scripts else None,
+                env_files=[str(p) for p in env_files] if env_files else None,
+            )
+        except ValueError as e:
+            # Re-raise with user-friendly message for CLI users
+            error_msg = str(e)
+            if "memory_db_type" in error_msg:
+                raise ValueError(
+                    f"Invalid database type '{database}'. Must be one of: InMemory, SQLite, AzureSQL"
+                ) from e
+            raise
+
+        # Store the merged configuration
+        self._config = config
+
+        # Extract values from config for internal use
+        # Use canonical mapping from configuration_loader
+        self._database = _MEMORY_DB_TYPE_MAP[config.memory_db_type]
+        self._initialization_scripts = config._resolve_initialization_scripts()
+        self._initializer_names = (
+            [ic.name for ic in config._initializer_configs] if config._initializer_configs else None
+        )
+        self._env_files = config._resolve_env_files()
 
         # Lazy-loaded registries
         self._scenario_registry: Optional[ScenarioRegistry] = None
         self._initializer_registry: Optional[InitializerRegistry] = None
         self._initialized = False
 
         # Configure logging
-        logging.basicConfig(level=getattr(logging, self._log_level))
+        logging.basicConfig(level=self._log_level)
 
     async def initialize_async(self) -> None:
         """Initialize PyRIT and load registries (heavy operation)."""
@@ -462,15 +500,15 @@ def validate_database(*, database: str) -> str:
     return database
 
 
-def validate_log_level(*, log_level: str) -> str:
+def validate_log_level(*, log_level: str) -> int:
     """
-    Validate log level.
+    Validate log level and convert to logging constant.
 
     Args:
         log_level: Log level string (case-insensitive).
 
     Returns:
-        Validated log level in uppercase.
+        Validated log level as logging constant (e.g., logging.WARNING).
 
     Raises:
         ValueError: If log level is invalid.
@@ -479,7 +517,8 @@ def validate_log_level(*, log_level: str) -> str:
     level_upper = log_level.upper()
     if level_upper not in valid_levels:
         raise ValueError(f"Invalid log level: {log_level}. Must be one of: {', '.join(valid_levels)}")
-    return level_upper
+    level_value: int = getattr(logging, level_upper)
+    return level_value
 
 
 def validate_integer(value: str, *, name: str = "value", min_value: Optional[int] = None) -> int:
@@ -734,6 +773,11 @@ async def print_initializers_list_async(*, context: FrontendCore, discovery_path
 
 # Shared argument help text
 ARG_HELP = {
+    "config_file": (
+        "Path to a YAML configuration file. Allows specifying database, initializers (with args), "
+        "initialization scripts, and env files. CLI arguments override config file values. "
+        "If not specified, ~/.pyrit/.pyrit_conf is loaded if it exists."
+    ),
     "initializers": "Built-in initializer names to run before the scenario (e.g., openai_objective_target)",
     "initialization_scripts": "Paths to custom Python initialization scripts to run before the scenario",
     "env_files": "Paths to environment files to load in order (e.g., .env.production .env.local). Later files "
@@ -768,7 +812,7 @@ def parse_run_arguments(*, args_string: str) -> dict[str, Any]:
             - max_retries: Optional[int]
             - memory_labels: Optional[dict[str, str]]
             - database: Optional[str]
-            - log_level: Optional[str]
+            - log_level: Optional[int]
             - dataset_names: Optional[list[str]]
             - max_dataset_size: Optional[int]
 

pyrit/cli/pyrit_scan.py

@@ -8,8 +8,10 @@
 """
 
 import asyncio
+import logging
 import sys
 from argparse import ArgumentParser, Namespace, RawDescriptionHelpFormatter
+from pathlib import Path
 from typing import Optional
 
 from pyrit.cli import frontend_core
@@ -34,6 +36,9 @@ def parse_args(args: Optional[list[str]] = None) -> Namespace:
   # Run a scenario with built-in initializers
   pyrit_scan foundry --initializers openai_objective_target load_default_datasets
 
+  # Run with a configuration file (recommended for complex setups)
+  pyrit_scan foundry --config-file ./my_config.yaml
+
   # Run with custom initialization scripts
   pyrit_scan garak.encoding --initialization-scripts ./my_config.py
 
@@ -45,10 +50,16 @@ def parse_args(args: Optional[list[str]] = None) -> Namespace:
         formatter_class=RawDescriptionHelpFormatter,
     )
 
+    parser.add_argument(
+        "--config-file",
+        type=Path,
+        help=frontend_core.ARG_HELP["config_file"],
+    )
+
     parser.add_argument(
         "--log-level",
         type=frontend_core.validate_log_level_argparse,
-        default="WARNING",
+        default=logging.WARNING,
         help="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) (default: WARNING)",
     )
 
@@ -182,6 +193,7 @@ def main(args: Optional[list[str]] = None) -> int:
                 return 1
 
         context = frontend_core.FrontendCore(
+            config_file=parsed_args.config_file,
             database=parsed_args.database,
             initialization_scripts=initialization_scripts,
             env_files=env_files,
@@ -194,7 +206,10 @@ def main(args: Optional[list[str]] = None) -> int:
         # Discover from scenarios directory
         scenarios_path = frontend_core.get_default_initializer_discovery_path()
 
-        context = frontend_core.FrontendCore(log_level=parsed_args.log_level)
+        context = frontend_core.FrontendCore(
+            config_file=parsed_args.config_file,
+            log_level=parsed_args.log_level,
+        )
         return asyncio.run(frontend_core.print_initializers_list_async(context=context, discovery_path=scenarios_path))
 
     # Verify scenario was provided
@@ -218,6 +233,7 @@ def main(args: Optional[list[str]] = None) -> int:
 
         # Create context with initializers
         context = frontend_core.FrontendCore(
+            config_file=parsed_args.config_file,
             database=parsed_args.database,
             initialization_scripts=initialization_scripts,
             initializer_names=parsed_args.initializers,

pyrit/cli/pyrit_shell.py

@@ -14,7 +14,8 @@
 import cmd
 import sys
 import threading
-from typing import TYPE_CHECKING
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
     from pyrit.models.scenario_result import ScenarioResult
@@ -98,7 +99,7 @@ def __init__(
         super().__init__()
         self.context = context
         self.default_database = context._database
-        self.default_log_level = context._log_level
+        self.default_log_level: Optional[int] = context._log_level
         self.default_env_files = context._env_files
 
         # Track scenario execution history: list of (command_string, ScenarioResult) tuples
@@ -217,24 +218,24 @@ def do_run(self, line: str) -> None:
                 return
 
         # Resolve env files if provided
-        resolved_env_files = None
+        resolved_env_files: Optional[list[Path]] = None
         if args["env_files"]:
             try:
-                resolved_env_files = frontend_core.resolve_env_files(env_file_paths=args["env_files"])
+                resolved_env_files = list(frontend_core.resolve_env_files(env_file_paths=args["env_files"]))
             except ValueError as e:
                 print(f"Error: {e}")
                 return
         else:
             # Use default env files from shell startup
-            resolved_env_files = self.default_env_files
+            resolved_env_files = list(self.default_env_files) if self.default_env_files else None
 
         # Create a context for this run with overrides
         run_context = frontend_core.FrontendCore(
             database=args["database"] or self.default_database,
             initialization_scripts=resolved_scripts,
             initializer_names=args["initializers"],
             env_files=resolved_env_files,
-            log_level=args["log_level"] or self.default_log_level,
+            log_level=args["log_level"] if args["log_level"] else self.default_log_level,
         )
         # Use the existing registries (don't reinitialize)
         run_context._scenario_registry = self.context._scenario_registry
@@ -453,6 +454,12 @@ def main() -> int:
         description="PyRIT Interactive Shell - Load modules once, run commands instantly",
     )
 
+    parser.add_argument(
+        "--config-file",
+        type=Path,
+        help=frontend_core.ARG_HELP["config_file"],
+    )
+
     parser.add_argument(
         "--database",
         choices=[frontend_core.IN_MEMORY, frontend_core.SQLITE, frontend_core.AZURE_SQL],
@@ -488,6 +495,7 @@ def main() -> int:
 
     # Create context (initializers are specified per-run, not at startup)
     context = frontend_core.FrontendCore(
+        config_file=args.config_file,
         database=args.database,
         initialization_scripts=None,
         initializer_names=None,

pyrit/common/path.py

@@ -33,6 +33,10 @@ def in_git_repo() -> bool:
 
 CONFIGURATION_DIRECTORY_PATH = pathlib.Path.home() / ".pyrit"
 
+# Default configuration file name and path
+DEFAULT_CONFIG_FILENAME = ".pyrit_conf"
+DEFAULT_CONFIG_PATH = CONFIGURATION_DIRECTORY_PATH / DEFAULT_CONFIG_FILENAME
+
 # Points to the root of the project
 HOME_PATH = pathlib.Path(PYRIT_PATH, "..").resolve()
 

pyrit/setup/__init__.py

@@ -3,12 +3,15 @@
 
 """Module containing initialization PyRIT."""
 
+from pyrit.setup.configuration_loader import ConfigurationLoader, initialize_from_config_async
 from pyrit.setup.initialization import AZURE_SQL, IN_MEMORY, SQLITE, MemoryDatabaseType, initialize_pyrit_async
 
 __all__ = [
     "AZURE_SQL",
     "SQLITE",
     "IN_MEMORY",
     "initialize_pyrit_async",
+    "initialize_from_config_async",
     "MemoryDatabaseType",
+    "ConfigurationLoader",
 ]