API Reference¶

This section contains the complete API documentation auto-generated from source code docstrings.

Core Modules¶

Security Manager¶

Security Provisioner Manager — core provisioning logic for IAM Groups, Roles, and Policies.

This module contains SecManager, the orchestrator for all security provisioning workflows. It exposes nine CLI actions arranged in a progressive safety model:

Local actions (no AWS calls):

validate-config — validate config YAML against tier schema
export-iam-policy — generate IAM deployment policy file
export-service-policies — generate service deployment policy files
create-prov-template — generate CloudFormation template

Read-only AWS actions:

validate-prov-template — validate template via AWS API
show-changes — preview deployment changes via ChangeSets
check-drift — detect infrastructure drift

Mutating AWS actions (require --force):

test-deploy — deploy with random test suffix
deploy — production deployment
delete-stack — delete stack and clean up Parameter Store

class sec_provisioner.core.sec_manager.SecManager(config_file_name, action, dry_run=False, log_level='INFO', force=False, app_config=None, schema_path=None, skip_schema_validation=False, profile_override=None, test_suffix=None)¶

Bases: object

Manages security provisioning operations based on configuration and action parameters.

This class serves as the core orchestrator for security provisioning workflows, with a progressive safety model that ensures secure and controlled provisioning while maintaining flexibility for different operational needs. It supports multiple deployment modes through its action parameter, enabling users to start with template generation and validation, proceed to change previews and drift detection, and finally execute safe test or production deployments.

It handles IAM group, role, and policy provisioning with config-driven CloudFormation template generation and multi-mode deployment safety.

Key Features:

Configuration validation against tier-specific schemas
IAM policy generation from YAML templates with least-privilege actions
Custom policy templates for services without AWS managed policies (KMS, Trusted Advisor)
CloudFormation template generation with tier-specific logic (startup/medium/enterprise)
S3 upload for templates exceeding the 51,200-byte TemplateBody limit
Deployment preview via CloudFormation ChangeSets
Infrastructure drift detection against deployed stacks
Safe test deployments with tenant ID isolation (random suffix)
Production deployments with prerequisite validation
Parameter Store integration for cross-provisioner output sharing
HTML documentation generation for templates and deployments

config_file_name¶

Path to configuration YAML file.

Type:: str

action¶

Action to perform (validate-config, export-iam-policy, export-service-policies, export-roles, export-groups, create-prov-template, validate-prov-template, show-changes, check-drift, test-deploy, deploy, delete-stack).

Type:: str

dry_run¶

If True, simulate operations without making changes.

Type:: bool

force¶

Force mutating AWS operations without confirmation.

Type:: bool

app_config¶

Application configuration dictionary.

Type:: Dict[str, Any]

schema_path¶

Optional custom validation schema path.

Type:: Optional[str]

skip_schema_validation¶

Skip schema validation if True.

Type:: bool

profile_override¶

Override security profile from config.

Type:: Optional[str]

Class Constants:: STACK_CREATE_WAITER_DELAY (int): Delay between stack creation checks (seconds) STACK_CREATE_WAITER_MAX_ATTEMPTS (int): Maximum stack creation wait attempts STACK_DELETE_WAITER_DELAY (int): Delay between stack deletion checks (seconds) STACK_DELETE_WAITER_MAX_ATTEMPTS (int): Maximum stack deletion wait attempts DRIFT_POLL_INTERVAL (int): Seconds between drift status checks DRIFT_POLL_TIMEOUT (int): Total timeout for drift detection (10 minutes) CHANGESET_POLL_INTERVAL (int): Seconds between changeset status checks CHANGESET_MAX_ATTEMPTS (int): Maximum attempts for changeset creation

Example

>>> from sec_provisioner.core import SecManager
>>> manager = SecManager(
...     config_file_name='sec-config.yaml',
...     action='export-iam-policy',
...     dry_run=False
... )
>>> exit_code = manager.execute()

STACK_CREATE_WAITER_DELAY = 10¶

STACK_CREATE_WAITER_MAX_ATTEMPTS = 60¶

STACK_DELETE_WAITER_DELAY = 10¶

STACK_DELETE_WAITER_MAX_ATTEMPTS = 60¶

DRIFT_POLL_INTERVAL = 10¶

DRIFT_POLL_TIMEOUT = 600¶

CHANGESET_POLL_INTERVAL = 5¶

CHANGESET_MAX_ATTEMPTS = 60¶

__init__(config_file_name, action, dry_run=False, log_level='INFO', force=False, app_config=None, schema_path=None, skip_schema_validation=False, profile_override=None, test_suffix=None)¶

Initializes class members from config file and parameters.

Parameters:

config_file_name (str) – Path to configuration YAML file.
action (str) – Action to perform.
dry_run (bool) – If True, simulate operations without making changes.
log_level (str) – Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
force (bool) – Force mutating AWS operations without confirmation.
app_config (Optional[Dict[str, Any]]) – Application configuration dictionary.
schema_path (Optional[str]) – Optional custom validation schema path.
skip_schema_validation (bool) – Skip schema validation if True.
profile_override (Optional[str]) – Override security profile from config.
test_suffix (str) – Suffix for test deployments (appended to resource names).

execute()¶

Execute the requested action.

Returns:: Exit code (0 for success, 1 for failure).
Return type:: int

Note

RuntimeError from validation helpers is caught and logged cleanly (no traceback). Any other unexpected exception is caught, logged with full traceback, and converted to exit code 1.

sec_provisioner.core.sec_manager.main()¶: Entry point for testing SecManager directly.

Configuration¶

Configuration Loader¶

class sec_provisioner.config.loader.AppConfig(config_dict)¶

Bases: object

Application configuration with embedded defaults.

Loads configuration from YAML files and provides convenient access to configuration values with automatic path resolution.

Features:

Loads config from provided dictionary (from YAML)
Resolves directory paths to absolute paths
Provides access to config values via get() method with dot notation
Handles directory path resolution and validation

__init__(config_dict)¶

Initializes the config object with config dictionary.

Parameters:: config_dict (Dict[str, Any]) – Configuration dictionary loaded from YAML.

get(key_path, default=None)¶

Gets a config value using dot notation.

Parameters:

key_path (str) – Dot-separated path (e.g., ‘directories.configs_dir’)
default (Any) – Default value if key not found

Returns:

Config value or default

Return type:

Any

get_directory(dir_name)¶

Gets a directory path as a Path object.

Parameters:: dir_name (str) – Directory name (configs_dir, reports_dir, etc.)
Returns:: Path object
Return type:: Path
Raises:: ValueError – If directory not configured

sec_provisioner.config.loader.load_app_config(custom_config_path=None)¶

Loads and returns application configuration.

Resolution order: 1. Custom config file (if provided via –app-config) 2. Embedded default config (always available)

Parameters:

custom_config_path (Optional[str]) – Optional path to custom config file

Returns:

AppConfig instance

Return type:

AppConfig

Raises:

FileNotFoundError – If custom config specified but not found
ValueError – If config file is invalid YAML

Utilities¶

HTML Generator¶

HTML documentation generator for security provisioning.

Provides three report types:

generate_template_documentation() — CloudFormation template overview
generate_deployment_documentation() — post-deployment stack report
generate_policy_documentation() — inline policy detail report

sec_provisioner.utils.html_generator.generate_template_documentation(config_file, template_file, cfn_template, output_path)¶

Generate HTML documentation for CloudFormation security template.

Parameters:

config_file (str) – Path to configuration YAML file.
template_file (str) – Path to generated CloudFormation template.
cfn_template (Dict[str, Any]) – Parsed CloudFormation template dictionary.
output_path (str) – Path where HTML file should be saved.

Returns:

Path to generated HTML file.

Return type:

str

sec_provisioner.utils.html_generator.generate_deployment_documentation(config_file, stack_name, region, stack_info, tier, security_profile, output_path)¶

Generate HTML documentation for security stack deployment.

Parameters:

config_file (str) – Path to configuration YAML file.
stack_name (str) – CloudFormation stack name.
region (str) – AWS region.
stack_info (Dict[str, Any]) – Stack information from describe_stacks.
tier (str) – Tier name (startup, medium, enterprise).
security_profile (str) – Security profile name.
output_path (str) – Path where HTML file should be saved.

Returns:

Path to generated HTML file.

Return type:

str

sec_provisioner.utils.html_generator.generate_policy_documentation(config_file, cfn_template, output_path)¶

Generate HTML documentation for all policies in the CloudFormation template.

Parameters:

config_file (str) – Path to configuration YAML file.
cfn_template (Dict[str, Any]) – Parsed CloudFormation template dictionary.
output_path (str) – Path where HTML file should be saved.

Returns:

Path to generated HTML file.

Return type:

str

License¶

License Validator¶

class sec_provisioner.license.validator.LicenseValidator¶

Bases: object

Validates product licenses against the AWS Marketplace License Manager.

This class handles the end-to-end license verification workflow, including secure communication with AWS APIs to confirm customer entitlements. To optimize performance and minimize latency, it employs an in-memory caching mechanism, reducing API calls for frequently validated tokens or customers.

product_sku¶

AWS Marketplace product sku to validate against.

Type:: str

region¶

AWS region for the Marketplace API.

Type:: str

license_client¶: Boto3 client for AWS Marketplace License Manager.

key_fingerprint¶: The fingerprint of the public key used for license validation.

entitlement_name¶: The name of the entitlement to check for in the AWS License Manager.

license_cache_file¶

Path to the local cache file.

Type:: str

cache_duration¶

Duration for which the cache is considered valid (hours).

Type:: timedelta

Integration Workflow:

Checks cache for active, unexpired validation result.
If missing/expired, calls CheckoutLicense API.
Validates product SKU and entitlement status.
Updates cache and returns validation status.

__init__()¶

Initialize the LicenseValidator with AWS Marketplace configuration.

Reads configuration from environment variables and sets up the AWS License Manager Client for license validation.

Environment Variables:: MARKETPLACE_PRODUCT_SKU: AWS Marketplace product SKU (required for validation) AWS_REGION: AWS region for Marketplace API (default: ‘us-east-1’)

verify_aws_marketplace_subscription()¶

Validate AWS Marketplace subscription via License Manager CheckoutLicense API.

Returns:: True if valid license, False otherwise
Return type:: bool

CLI Interface¶

class sec_provisioner.cli.SecProvisionerCLI¶

Bases: BaseCLI

CLI for Security Provisioner Tool.

Extends BaseCLI to implement security-specific actions and arguments. Supports 11 actions grouped by safety level:

Local: validate-config, export-iam-policy, export-service-policies, export-groups, export-roles, create-prov-template, validate-prov-template
Read-only: show-changes, check-drift
Mutating: test-deploy, deploy, delete-stack

Includes AWS Marketplace license validation before executing any actions.

__init__()¶: Initialize the Security Provisioner CLI.

is_action_required()¶

Determine if an action argument is required for this CLI.

Returns:: Always True for this CLI.
Return type:: bool

get_actions()¶

Return the list of valid actions for the Security Provisioner CLI.

Returns:: List of action strings.
Return type:: List[str]

get_actions_help()¶

Return help text describing all available actions.

Returns:: Formatted help text grouped by safety level.
Return type:: str

get_manager_class()¶

Return the manager class for this CLI.

Returns:: SecManager class reference.
Return type:: Type[Any]

get_example_usage()¶

Return example usage instructions.

Detects Docker environment via /.dockerenv or /proc/1/cgroup and adjusts command examples accordingly.

Returns:: Example usage string with Docker or native CLI commands.
Return type:: str

add_custom_arguments(parser)¶

Add Security Provisioner-specific CLI arguments.

Parameters:: parser (Any) – The argparse parser to add arguments to.
Return type:: None

create_manager_instance(args)¶

Create a new SecManager instance.

Parameters:: args (argparse.Namespace) – Parsed command-line arguments.
Returns:: Instance initialized with CLI arguments and app config.
Return type:: SecManager

requires_force(action)¶

Determine if an action requires the --force flag.

Parameters:: action (str) – The action being performed.
Returns:: True for mutating AWS operations (deploy, delete-stack).
Return type:: bool

sec_provisioner.cli.main()¶

Entry point for Security Provisioner CLI.

Validates AWS Marketplace license before running the CLI. Exits with code 1 if license validation fails.