Metadata-Version: 2.4
Name: deceptionlogic
Version: 1.4.1
Summary: A python wrapper and CLI tool for the Deception Logic API.
Home-page: http://deceptionlogic.com
Download-URL: https://github.com/deceptionlogic/deception-api
Author: Deception Logic, Inc.
Author-email: info@deceptionlogic.com
License: MIT
Keywords: wrapper library deception logic api cli
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: future
Requires-Dist: requests
Requires-Dist: boto3
Requires-Dist: typer[all]
Requires-Dist: rich
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Deception Logic API

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

[![Latest Version](https://img.shields.io/pypi/v/deceptionlogic.svg)](https://pypi.python.org/pypi/deceptionlogic/)
[![Build Status](https://travis-ci.org/deceptionlogic/deception-api.svg?branch=master)](https://travis-ci.org/deceptionlogic/deception-api)

## Installation

```bash
pip install deceptionlogic
```

Or install from source:

```bash
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:

```bash
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:

```bash
# 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:

```bash
# 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

```python
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

```bash
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

```bash
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

```bash
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

```bash
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

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

### Alerts

```bash
dl alert list                    # List all alerts
```

### Tokens

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

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

### Additional Resources

```bash
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

| Old Command | New Command |
|------------|-------------|
| `deception agents --list` | `dl agent list` |
| `deception agents --id <id>` | `dl agent get <id>` |
| `deception profiles --list` | `dl profile list` |
| `deception profiles --id <guid>` | `dl profile get <guid>` |
| `deception services --list` | `dl service list` |
| `deception services --id <guid>` | `dl service get <guid>` |
| `deception alerts --list` | `dl alert list` |
| `deception events --list` | `dl event list` |

### 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](MIGRATION_GUIDE.md) for detailed migration instructions.

## API Client Library

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

```python
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

```bash
# 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:

```bash
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](MIGRATION_GUIDE.md) - Detailed guide for migrating from old CLI
- [Proposed CLI Structure](PROPOSED_CLI_STRUCTURE.md) - Complete command reference
- [Postman Comparison](POSTMAN_COMPARISON.md) - API endpoint coverage analysis

## License

MIT

## Support

For issues, questions, or contributions, please visit the [GitHub Project Page](https://github.com/deceptionlogic/deception-api).
