cisco-scc-sdk 1.0.4

Python SDK for Cisco Security Cloud Control Platform Management APIs

Cisco Security Cloud Control Python SDK

A Python SDK for interacting with the Cisco Security Cloud Control Platform Management APIs.

Installation

pip3 install cisco-scc-sdk

Or install from source:

pip3 install .

Using a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate && pip install -e .

Quick Start

from scc_sdk import Client

# Initialize the client with your access token
client = Client(access_token="your_bearer_token_here")

# Work with organizations
organizations = client.organizations.list()
org = client.organizations.get(org_id="550e8400-e29b-41d4-a716-446655440000")
new_org = client.organizations.create(name="New Org", region_code="NAM")

# Work with subscriptions
subscriptions = client.subscriptions.list(org_id="org-uuid")
subscription = client.subscriptions.get(org_id="org-uuid", subscription_id="sub-uuid")

# Work with groups
groups = client.groups.list(org_id="org-uuid")
group = client.groups.get(org_id="org-uuid", group_id="group-uuid")

Features

• Simple Authentication: Just pass your bearer token
• Resource-based API: Organized into logical resource classes
• Type Hints: Full type hint support for better IDE integration
• Context Manager Support: Use with with statement for automatic cleanup
• Comprehensive Error Handling: Custom exceptions for different error types

Configuration

The SDK uses a configurable base URL. By default, it points to https://api.security.cisco.com/v1.

To use a different URL:

client = Client(
    access_token="your_token",
    base_url="https://api.security.cisco.com",
    base_path="v1"
)

Usage Examples

Cisco Live Example

For a complete end-to-end example demonstrating organization setup including subscription claiming, user invitations, group creation, and role assignments, see examples/cisco_live_example.py.

To run the Cisco Live example:

1. Get your API Access Token: Generate an API key access token from the Security Cloud Control console

2. Create or identify your Organization: Note the Organization ID you want to configure

3. Update the configuration in cisco_live_example.py:

   • Set ACCESS_TOKEN to your API key access token
   • Set ORG_ID to your organization ID
   • Update USERS_TO_INVITE with the users you want to invite
   • Set SECURE_ACCESS_CLAIM_CODE and FIREWALL_CLAIM_CODE with your subscription claim codes

4. Run the script:

   python3 examples/cisco_live_example.py
   

This example demonstrates a complete workflow including:

• Retrieving organization details
• Claiming Secure Access and Firewall subscriptions
• Inviting users to the organization
• Creating an admin group
• Assigning product roles to the group

Using Context Manager

with Client(access_token="your_token") as client:
    orgs = client.organizations.list()
    # Session is automatically closed when exiting the context

Organizations

# List organizations with filtering and pagination
orgs = client.organizations.list(
    name="Acme",
    type="STANDALONE",
    region_code="NAM",
    max=50,
    sort_by="name",
    order="ASC"
)

# Get a specific organization
org = client.organizations.get(org_id="550e8400-e29b-41d4-a716-446655440000")

# Create a new organization
new_org = client.organizations.create(
    name="New Organization",
    region_code="NAM",
    type="STANDALONE"
)

# Update an organization
updated_org = client.organizations.update(
    org_id="550e8400-e29b-41d4-a716-446655440000",
    name="Updated Name"
)

Subscriptions

org_id = "550e8400-e29b-41d4-a716-446655440000"

# List subscriptions
subscriptions = client.subscriptions.list(org_id=org_id)

# Get a specific subscription
subscription = client.subscriptions.get(
    org_id=org_id,
    subscription_id="3742d652-6740-489c-b628-143f00690fea"
)

# Create a subscription with claim code
new_subscription = client.subscriptions.create(
    org_id=org_id,
    claim_code="PHJZ-DWMF-ZBYH-FYMB",
    type="STANDALONE"
)

# Read claim code details before creating
claim_info = client.subscriptions.read_claim_code(
    org_id=org_id,
    claim_code="PHJZ-DWMF-ZBYH-FYMB"
)

# Update subscription (activate/deactivate product)
updated_sub = client.subscriptions.update(
    org_id=org_id,
    subscription_id="sub-uuid",
    product_id="product-uuid",
    status=True,
    region_code="NAM",
    initial_admin="[e-mail]"
)

# Patch subscription (update SKU quantities for managed orgs)
patched_sub = client.subscriptions.patch(
    org_id=org_id,
    subscription_id="sub-uuid",
    skus=[
        {"name": "E3S-AIDEF-ADV", "quantity": 10},
        {"name": "CPT-SEC-ADV", "quantity": 50}
    ]
)

Groups

org_id = "550e8400-e29b-41d4-a716-446655440000"

# List groups
groups = client.groups.list(org_id=org_id)

# Get a specific group
group = client.groups.get(
    org_id=org_id,
    group_id="e980e881-b61f-11f0-a9b4-06fbd2118f4e"
)

# Create a new group
new_group = client.groups.create(
    org_id=org_id,
    name="Engineering Team",
    description="Engineering department group",
    applies_to="SOME_MANAGED"
)

# Update a group
updated_group = client.groups.update(
    org_id=org_id,
    group_id="group-uuid",
    name="Updated Team Name",
    description="Updated description"
)

# Delete a group
client.groups.delete(org_id=org_id, group_id="group-uuid")

# Remove shared group from managed organization
client.groups.remove_shared_group(org_id=org_id, group_id="group-uuid")

Token Refresh

# Refresh access token using refresh token
new_tokens = client.tokens.refresh(
    org_id="org-uuid",
    api_key_id="key-uuid",
    refresh_token="your_refresh_token"
)

access_token = new_tokens["access_token"]
refresh_token = new_tokens["refresh_token"]
expires_in = new_tokens["expires_in"]

Error Handling

The SDK provides custom exceptions for different error scenarios:

from scc_sdk import (
    Client,
    SCCError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    ForbiddenError,
    ServerError
)

try:
    client = Client(access_token="your_token")
    org = client.organizations.get(org_id="invalid-uuid")
except AuthenticationError:
    print("Invalid access token")
except NotFoundError:
    print("Organization not found")
except ValidationError:
    print("Invalid request data")
except ForbiddenError:
    print("Access forbidden")
except ServerError:
    print("Server error occurred")
except SCCError as e:
    print(f"API error occurred: {e}")

API Resources

Organizations Resource

• list() - List organizations with filtering
• get(org_id) - Get organization by ID
• create(name, region_code, type) - Create new organization
• update(org_id, name) - Update organization name

Subscriptions Resource

• list(org_id, name) - List subscriptions
• get(org_id, subscription_id) - Get subscription by ID
• create(org_id, claim_code, type, products) - Create subscription
• update(org_id, subscription_id, ...) - Update subscription
• patch(org_id, subscription_id, skus, ...) - Patch subscription SKUs
• read_claim_code(org_id, claim_code) - Validate claim code

Groups Resource

• list(org_id) - List groups
• get(org_id, group_id) - Get group by ID
• create(org_id, name, description, applies_to) - Create group
• update(org_id, group_id, name, description) - Update group
• delete(org_id, group_id) - Delete group
• remove_shared_group(org_id, group_id) - Remove shared group

Tokens Resource

• refresh(org_id, api_key_id, refresh_token) - Refresh access token

Development

Running Tests

pip3 install -e ".[dev]"
pytest

Code Formatting

black scc_sdk/
flake8 scc_sdk/
mypy scc_sdk/

API Documentation

For full API documentation, refer to the Cisco Security Cloud Control API Documentation.

Contributing

Thanks for your interest in contributing! There are many ways to contribute to this project. Get started here.

Support

For questions, issues, or feedback regarding this SDK, please contact the Cisco SCC SDK Team:

📧 Email: [e-mail]

License

This library is distributed under the Apache 2.0 license found in the LICENSE file.