Deception Logic API

Deception Logic API Client Library - A Python wrapper and modern CLI for the Deception Logic API.

Installation

pip install deceptionlogic

Or install from source:

git clone https://github.com/deceptionlogic/deception-api.git
cd deception-api
pip install -e .

Quick Start

Environment Setup

Set your API credentials as environment variables:

export DECEPTIONLOGIC_KEYID="your-key-id"
export DECEPTIONLOGIC_SECRET="your-secret-key"
export DECEPTIONLOGIC_BASEURL="https://api.deceptionlogic.net/"  # Optional, defaults to production

CLI Usage (New Modern CLI)

The new CLI uses the dl command with a modern, type-safe interface:

# Get help
dl --help

# List all agents
dl agent list

# Get specific agent
dl agent get <agent-id>

# List profiles
dl profile list

# Create a profile
dl profile create --name "Web Server" --service <service-guid-1> --service <service-guid-2>

# List services
dl service list

# Create a service
dl service create --name "Echo" --module "Echo_tcp" --port 7

# List events (with time filters)
dl event list --from 1d --until 1h

# List alerts
dl alert list

# Manage cloud agents
dl cloud-agent list
dl cloud-agent create --number 2 --provider aws --location us-east-1

# Token management
dl token list
dl token create --type aws --target "AWS API Key"
dl token download <token-guid> --output token.html

# Configuration management
dl config alert list
dl config alert create --type email --value "alerts@example.com"
dl config event-forwarder set --on true --type "Sumo Logic" --url <url>

CLI Usage (Legacy - Still Supported)

The old CLI commands still work for backwards compatibility:

# Old style commands
deception agents --list
deception profiles --id <guid>
deception alerts --list

Run deception --help or dl --help for a complete list of CLI options.

Module Usage

from deceptionlogic import api

# Initialize client
delo = api.Client('keyid', 'secret')

# Optional: Set custom base URL
delo.base_url = "https://api.deceptionlogic.net/"

# Authenticate
auth = delo.authenticate()
if auth["status"] == "success":
    delo.token = auth["token"]
    delo.identifier = auth["id"]

# Get agents
agents = delo.get_agents()

# Get alerts
alerts = delo.get_alerts()

# Get events with filters
events = delo.get_events(from_time="1d", until="1h")

# Create a profile
profile = delo.create_profile(
    name="Web Server",
    services=["service-guid-1", "service-guid-2"]
)

# Create a service
service = delo.create_service(
    name="Echo",
    module="Echo_tcp",
    port=7,
    description="Echo service"
)

# Update agent profile
delo.set_agent_profile(agent_id="agent-123", profile_guid="profile-guid")

CLI Command Reference

Agents

dl agent list                    # List all agents
dl agent get <agent-id>          # Get agent by ID
dl agent update-profile <id> --profile-guid <guid>  # Update agent profile

Cloud Agents

dl cloud-agent list [--status <status>] [--guid <guid>]  # List cloud agents
dl cloud-agent create --number <n> --provider <provider> --location <location>  # Create cloud agents
dl cloud-agent delete <deployment-guid>  # Delete cloud agent

Profiles

dl profile list                  # List all profiles
dl profile get <guid>            # Get profile by GUID
dl profile create --name <name> [--description <desc>] --service <guid>...  # Create profile
dl profile update <guid> [--name <name>] [--description <desc>] [--service <guid>...]  # Update profile
dl profile delete <guid>         # Delete profile

Services

dl service list                  # List all services
dl service get <guid>           # Get service by GUID
dl service create --name <name> --module <module> --port <port> [--description <desc>] [--config <key=value>...]  # Create service
dl service update <guid> [--name <name>] [--module <module>] [--port <port>] [--description <desc>] [--config <key=value>...]  # Update service
dl service delete <guid>        # Delete service

Events

dl event list [--from <time>] [--until <time>]  # List events with optional time filters

Alerts

dl alert list                    # List all alerts

Tokens

dl token list                    # List all tokens
dl token get <guid>              # Get token by GUID
dl token create --type <type> --target <target> [--description <desc>]  # Create token
dl token delete <guid>           # Delete token
dl token download <guid> [--output <file>]  # Download token HTML
dl token events [--from <time>] [--until <time>]  # Get token events
dl token alerts [--from <time>] [--until <time>]  # Get token alerts

Configuration

Alert Configuration

dl config alert list             # List alert configurations
dl config alert get <guid>       # Get alert config by GUID
dl config alert create --type <type> --value <value> [--description <desc>]  # Create alert config
dl config alert update <guid> [--type <type>] [--value <value>] [--description <desc>]  # Update alert config
dl config alert delete <guid>    # Delete alert config

Event Forwarder

dl config event-forwarder get    # Get event forwarder configuration
dl config event-forwarder set --on <true|false> --type <type> --url <url>  # Set event forwarder

Authorized Sources

dl config auth-source list       # List authorized sources
dl config auth-source get <guid> # Get authorized source by GUID
dl config auth-source create --source <source> [--description <desc>]  # Create authorized source
dl config auth-source delete <guid>  # Delete authorized source

Auto Config Keys

dl config autoconfig-key list    # List auto config keys
dl config autoconfig-key get <guid>  # Get auto config key by GUID
dl config autoconfig-key create --key <key> --value <value> [--description <desc>]  # Create auto config key
dl config autoconfig-key update <guid> [--key <key>] [--value <value>] [--description <desc>]  # Update auto config key
dl config autoconfig-key delete <guid>  # Delete auto config key

Users

dl config user list              # List users
dl config user get <guid>        # Get user by GUID
dl config user delete <guid>     # Delete user

Additional Resources

dl plugin list                   # List plugins
dl monitor list                  # List monitors
dl monitor log list [--agent-id <id>]  # List monitor logs
dl agent-log list [--agent-id <id>]    # List agent logs
dl audit-log list [--from <time>] [--until <time>]  # List audit logs

Migration from Old CLI

The old deception commands are still supported, but we recommend migrating to the new dl commands for better type safety and complete API coverage.

Command Mapping

New Features Not in Old CLI

• CRUD Operations: Create, update, and delete profiles, services, and other resources
• Cloud Agents: Full lifecycle management
• Configuration Management: Alert configs, event forwarders, authorized sources, auto-config keys, users
• Token Management: Complete token lifecycle with download and event/alert queries
• Better Error Handling: Type-safe commands with clear error messages
• Rich Output: Pretty-printed JSON with --pretty flag

See MIGRATION_GUIDE.md for detailed migration instructions.

API Client Library

The Python client library provides typed methods for all API endpoints:

from deceptionlogic import api

client = api.Client(keyid, secret)
auth = client.authenticate()

# Agents
agents = client.get_agents()
agent = client.get_agent(agent_id)
client.set_agent_profile(agent_id, profile_guid)

# Cloud Agents
cloud_agents = client.list_cloud_agents(status="deployed")
client.create_cloud_agents(number=2, provider="aws", location="us-east-1")
client.delete_cloud_agent(deployment_guid)

# Profiles
profiles = client.get_profiles()
profile = client.get_profile(guid)
new_profile = client.create_profile(name="Test", services=["guid1", "guid2"])
client.update_profile(guid, name="Updated", services=["guid1"])
client.delete_profile(guid)

# Services
services = client.get_services()
service = client.get_service(guid)
new_service = client.create_service(name="Echo", module="Echo_tcp", port=7)
client.update_service(guid, name="Updated")
client.delete_service(guid)

# Events & Alerts
events = client.get_events(from_time="1d", until="1h")
alerts = client.get_alerts()

# Tokens
tokens = client.list_tokens()
token = client.create_token(token_type="aws", token_target="target")
token_events = client.token_events(from_time="1d")
token_alerts = client.token_alerts(from_time="1d")

# Configuration
alert_configs = client.list_alert_configs()
client.create_alert_config(alert_type="email", value="alerts@example.com")
client.set_event_forwarder(on=True, forwarder_type="Sumo Logic", url="https://...")

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run specific test file
pytest tests/test_client.py

# Run with coverage
pytest --cov=deceptionlogic

Verifying CLI Parity

The project includes a script to verify that all API endpoints have CLI coverage:

python scripts/verify_cli_parity.py "Deception Logic API.postman_collection.json"

This script is automatically run in CI to ensure API parity.

Project Structure

deceptionlogic/
├── api/
│   └── client.py          # API client library
├── cli/
│   ├── main.py            # CLI entry point
│   ├── common.py          # Common utilities
│   ├── agents.py          # Agent commands
│   ├── profiles.py        # Profile commands
│   ├── services.py        # Service commands
│   ├── events.py          # Event commands
│   ├── alerts.py          # Alert commands
│   ├── tokens.py          # Token commands
│   ├── config.py          # Configuration commands
│   └── ...                # Other command modules
└── bin/
    └── deception          # Legacy CLI entry point

Examples

See example.py for inline usage comments and reference implementation.

Documentation

• Migration Guide - Detailed guide for migrating from old CLI
• Proposed CLI Structure - Complete command reference
• Postman Comparison - API endpoint coverage analysis

License

MIT

Support

For issues, questions, or contributions, please visit the GitHub Project Page.