Skip to main content

Boto3 Governance Wrapper

FieldValue
Document IDASCEND-SDK-009
Version2026.04
Last UpdatedApril 2026
AuthorAscend Engineering Team
PublisherOW-KAI Technologies Inc.
ClassificationEnterprise Client Documentation
ComplianceSOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 10 minutes | Skill Level: Beginner

Overview​

The ASCEND Boto3 Wrapper adds transparent AI governance to all AWS SDK operations. With a single line of code, every boto3 call is evaluated against your governance policies.

API Key Security

Store API keys in environment variables, never in source code or version control. The Boto3 wrapper transmits action metadata to ASCEND for governance evaluation before executing AWS API calls.

How It Works​

┌─────────────────────────────────────────────────────────────────────┐
│                    BOTO3 GOVERNANCE FLOW                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐              │
│  │   Your      │    │   ASCEND    │    │    AWS      │              │
│  │   Code      │───▶│   Wrapper   │───▶│   API       │              │
│  │             │    │             │    │             │              │
│  │ s3.delete() │    │ ✓ Risk=HIGH │    │ Bucket      │              │
│  │             │    │ ✓ APPROVED  │    │ Deleted     │              │
│  └─────────────┘    └─────────────┘    └─────────────┘              │
│                            │                                         │
│                            │                                         │
│                            ▼                                         │
│                    ┌─────────────┐                                   │
│                    │   ASCEND    │                                   │
│                    │   Platform  │                                   │
│                    │             │                                   │
│                    │ Policy      │                                   │
│                    │ Evaluation  │                                   │
│                    │ Audit Log   │                                   │
│                    └─────────────┘                                   │
│                                                                       │
└─────────────────────────────────────────────────────────────────────┘

Installation​

pip install ascend-boto3-wrapper==1.2.0

Package Info: ascend-boto3-wrapper on PyPI | Version: 1.2.0 | License: Proprietary

Requirements​

  • Python 3.8+
  • boto3 >= 1.26.0

Quick Start​

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/wrapper.py:349
from ascend_boto3 import enable_governance

# Enable governance globally - one line!
enable_governance(api_key="owkai_your_key_here")

# All boto3 operations now go through ASCEND
import boto3

# This will require approval for HIGH risk
s3 = boto3.client('s3')
s3.delete_bucket(Bucket='production-data')  # Governed!

# This will auto-approve for LOW risk
s3.list_buckets()  # Governed but auto-approved

Configuration Options​

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/wrapper.py:349
from ascend_boto3 import enable_governance

enable_governance(
    # Required
    api_key="owkai_your_key_here",

    # Optional
    base_url="https://pilot.owkai.app",
    agent_id="aws-automation-001",
    agent_name="AWS Automation Agent",

    # Auto-approve settings
    auto_approve_low_risk=True,    # Auto-approve LOW risk ops
    auto_approve_medium_risk=False, # Require approval for MEDIUM

    # Bypass rules
    bypass_services={"cloudwatch", "logs"},  # Skip these services
    bypass_operations={"s3.list_buckets"},   # Skip specific operations

    # Testing
    dry_run=False  # Log decisions without enforcing
)
OptionTypeDefaultDescription
api_keystrRequiredASCEND API key
base_urlstrhttps://pilot.owkai.appAPI endpoint
agent_idstrAuto-generatedUnique agent identifier
agent_namestrAWS Boto3 AgentHuman-readable name
auto_approve_low_riskboolTrueAuto-approve LOW risk
auto_approve_medium_riskboolFalseAuto-approve MEDIUM risk
bypass_servicesSet[str]{}Services to skip
bypass_operationsSet[str]{}Operations to skip
dry_runboolFalseLog without enforcing

Risk Classification​

The wrapper automatically classifies AWS operation risk:

Risk Levels by Service​

Risk LevelServices/OperationsExamples
LOWRead-only operationss3.get_object, ec2.describe_instances
MEDIUMWrite operationss3.put_object, dynamodb.put_item
HIGHDelete operationss3.delete_bucket, ec2.terminate_instances
CRITICALIAM/Security changesiam.create_user, kms.delete_key

Classification Logic​

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/risk_classifier.py
from ascend_boto3.risk_classifier import classify_operation_risk, RiskLevel

# Check operation risk before execution
risk_score, risk_level = classify_operation_risk(
    service='s3',
    operation='delete_bucket',
    params={'Bucket': 'my-bucket'}
)

print(f"Risk: {risk_level.value} ({risk_score})")
# Output: Risk: high (75)

Bypass Rules​

Skip governance for specific services or operations:

Bypass by Service​

enable_governance(
    api_key="owkai_xxx",
    bypass_services={
        "cloudwatch",     # Skip all CloudWatch operations
        "logs",           # Skip all CloudWatch Logs
        "cloudformation"  # Skip all CloudFormation
    }
)

Bypass by Operation​

enable_governance(
    api_key="owkai_xxx",
    bypass_operations={
        "s3.list_buckets",           # Skip S3 list buckets
        "ec2.describe_instances",    # Skip EC2 describe
        "sts.get_caller_identity"    # Skip STS identity check
    }
)

Handling Decisions​

Approved Actions​

Approved actions execute normally:

s3 = boto3.client('s3')

# This will be logged and proceed if approved
response = s3.get_object(Bucket='my-bucket', Key='data.json')
# Returns normal boto3 response

Denied Actions​

Denied actions raise PermissionError:

from ascend_boto3 import enable_governance

enable_governance(api_key="owkai_xxx")

try:
    s3 = boto3.client('s3')
    s3.delete_bucket(Bucket='critical-production-data')
except PermissionError as e:
    print(f"Operation denied: {e}")
    # Output: Operation denied by Ascend governance.
    # Reason: Bucket deletion requires manager approval.
    # Action ID: act_123xyz

Dry Run Mode​

Test governance without blocking operations:

enable_governance(
    api_key="owkai_xxx",
    dry_run=True  # Log decisions but don't enforce
)

# All operations execute, but decisions are logged
s3 = boto3.client('s3')
s3.delete_bucket(Bucket='test-bucket')
# Logs: "[DRY RUN] Would execute: s3.delete_bucket"
# Actually executes the delete

Disabling Governance​

from ascend_boto3 import enable_governance, disable_governance, is_governance_enabled

enable_governance(api_key="owkai_xxx")

# All subsequent boto3 operations are governed

# Disable when done
disable_governance()

# Check status
if is_governance_enabled():
    print("Governance is active")
else:
    print("Governance is disabled")

Production Example​

#!/usr/bin/env python3
"""
Production AWS Automation with ASCEND Governance
"""
import os
import logging
import boto3
from ascend_boto3 import enable_governance

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def setup_governance():
    """Initialize governance with production settings."""
    enable_governance(
        api_key=os.environ["ASCEND_API_KEY"],
        agent_id="aws-automation-prod",
        agent_name="AWS Production Automation",

        # Auto-approve only LOW risk in production
        auto_approve_low_risk=True,
        auto_approve_medium_risk=False,

        # Skip monitoring services
        bypass_services={"cloudwatch", "logs"},

        # Never skip delete operations
        # bypass_operations={}
    )
    logger.info("ASCEND governance enabled")

def cleanup_old_buckets():
    """Delete S3 buckets older than 90 days."""
    s3 = boto3.client('s3')

    try:
        response = s3.list_buckets()  # AUTO-APPROVED (low risk)

        for bucket in response['Buckets']:
            bucket_name = bucket['Name']

            if should_delete_bucket(bucket):
                logger.info(f"Requesting deletion of {bucket_name}")

                try:
                    # REQUIRES APPROVAL (high risk)
                    s3.delete_bucket(Bucket=bucket_name)
                    logger.info(f"Deleted {bucket_name}")

                except PermissionError as e:
                    logger.warning(f"Deletion denied: {e}")
                    # Queue for manual review
                    queue_for_review(bucket_name, str(e))

    except Exception as e:
        logger.error(f"Cleanup failed: {e}")
        raise

def should_delete_bucket(bucket):
    """Check if bucket should be deleted."""
    # Your business logic here
    return False

def queue_for_review(bucket_name, reason):
    """Queue bucket for manual review."""
    logger.info(f"Queued {bucket_name} for manual review: {reason}")

if __name__ == "__main__":
    setup_governance()
    cleanup_old_buckets()

Fallback Behavior​

When ASCEND is unavailable:

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/wrapper.py:176
# For HIGH/CRITICAL risk: FAIL CLOSED (deny)
# For LOW/MEDIUM risk: FAIL OPEN (allow with warning)

# The wrapper logs failures and acts accordingly:
# INFO: [Ascend Governance] s3.delete_bucket - Risk: HIGH (75) - DENIED
# WARNING: Governance evaluation failed, denying high-risk operation

Monitoring​

CloudWatch Metrics​

The wrapper logs structured metrics:

{
    "service": "s3",
    "operation": "delete_bucket",
    "risk_score": 75,
    "risk_level": "high",
    "decision": "approved",
    "action_id": "act_123xyz",
    "latency_ms": 45
}

Log Analysis​

# Find denied operations
grep "DENIED" /var/log/app.log

# Find high-risk approvals
grep "Risk: HIGH.*APPROVED" /var/log/app.log

Troubleshooting​

IssueCauseSolution
ValueError: API key requiredMissing API keySet ASCEND_API_KEY env var
PermissionError on low-riskStrict policiesCheck Smart Rules in dashboard
All operations deniedAPI connectivityVerify network access to ASCEND
Operations executing without governanceNot enabledCall enable_governance() first

Supported AWS Services​

The wrapper supports all boto3 services. Risk classification is available for:

  • S3 - Object storage operations
  • EC2 - Compute instance management
  • RDS - Database operations
  • DynamoDB - NoSQL operations
  • Lambda - Function management
  • IAM - Identity and access
  • KMS - Key management
  • SNS/SQS - Messaging
  • Secrets Manager - Secrets operations

Other services use default risk classification based on operation type.

Next Steps​

Document Version: 2026.04 | Last Updated: April 2026