CLI Reference

The taxii-cli command-line tool manages DARWIS TAXII.

Global Options

taxii-cli [OPTIONS] <COMMAND>

Database URL can also be set via DATABASE_URL environment variable.

Commands

sync

Synchronize configuration from YAML file. Manages services, collections, and accounts.

taxii-cli sync <CONFIG_FILE>

Examples:

# Sync configuration
taxii-cli sync data-config.yaml

The sync behavior is controlled via YAML options (not CLI flags). See Sync Configuration below.

api-root

Manage TAXII 2.x API roots.

api-root list

List all API roots.

taxii-cli api-root list

api-root add

Create a new API root.

taxii-cli api-root add [OPTIONS]

Examples:

taxii-cli api-root add --title "Threat Intel" --default
taxii-cli api-root add --title "Partner Sharing" --description "Shared with partners"

collection

Manage TAXII 2.x collections.

collection list

List collections in an API root.

taxii-cli collection list --api-root-id <UUID>

collection add

Create a new collection.

taxii-cli collection add [OPTIONS]

Examples:

taxii-cli collection add \
  --api-root-id a1b2c3d4-... \
  --title "IOC Feed" \
  --alias iocs

taxii-cli collection add \
  --api-root-id a1b2c3d4-... \
  --title "Public Intel" \
  --public

account

Manage user accounts.

Tip

Accounts are created via the sync command with a YAML configuration file. See the examples section below.

account list

List all accounts.

taxii-cli account list

account delete

Delete an account.

taxii-cli account delete --username <NAME>

content

Manage content blocks (TAXII 1.x).

content delete

Delete content blocks from collections.

taxii-cli content delete [OPTIONS]

Examples:

# Delete content from January 2024
taxii-cli content delete \
  --collection my-collection \
  --begin 2024-01-01T00:00:00Z \
  --end 2024-02-01T00:00:00Z

# Delete from multiple collections with messages
taxii-cli content delete \
  --collection coll-a \
  --collection coll-b \
  --begin 2024-01-01T00:00:00Z \
  --with-messages

Environment Variables

Sync Configuration

The sync command behavior is controlled entirely via YAML options, making configuration declarative and version-controllable.

YAML Structure

# Entity cleanup behavior (what happens to entities NOT in this file)
prune_services: false            # Delete services not in config (default: false)
collections_not_in_config: ignore # ignore | disable | delete (default: ignore)
prune_accounts: false            # Delete accounts not in config (default: false)

# Entity definitions
services:
  - id: discovery
    type: DISCOVERY
    # ...

collections:
  - name: my-collection
    # ...

accounts:
  - username: admin
    # ...

Cleanup Options

Collection Cleanup Actions

Collections support three actions since they have an “available” flag:

Caution

delete permanently removes collections and their content. Use with care.

Common Patterns

Additive sync (default): Only create/update, never delete:

# All cleanup options default to safe values
services:
  - id: inbox
    # ...

Full declarative control: Config is the source of truth:

prune_services: true
collections_not_in_config: delete
prune_accounts: true

services:
  # Only these services will exist
collections:
  # Only these collections will exist
accounts:
  # Only these accounts will exist

Accounts-only sync: Manage accounts without affecting other entities:

prune_accounts: true
# prune_services and collections_not_in_config default to safe values

accounts:
  - username: admin
    password: secret
    is_admin: true

Collection Reference Validation

When syncing accounts, all collection references in permissions are validated:

• TAXII 1.x permissions: collection name must exist
• TAXII 2.x permissions: collection UUID must exist

If any referenced collection doesn’t exist, the sync fails with an error:

Account 'analyst' references non-existent collections:
  - 'invalid-collection' (TAXII 1.x)
  - '00000000-0000-0000-0000-000000000000' (TAXII 2.x)

Examples

Complete Setup Workflow

# 1. Create API root
taxii-cli api-root add --title "Intel Hub" --default

# 2. List to get the UUID
taxii-cli api-root list
# ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 3. Create collections
taxii-cli collection add \
  --api-root-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --title "Indicators" \
  --alias indicators

taxii-cli collection add \
  --api-root-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --title "Malware" \
  --alias malware

# 4. List collections to get UUIDs
taxii-cli collection list \
  --api-root-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 5. Create accounts with permissions
cat > data-config.yaml << EOF
accounts:
  - username: analyst
    password: analyst123
    permissions:
      86c1741e-7e95-4b17-8940-a8f83eb5fe32: [read, write]
      24574d4d-d29a-4b53-80c0-be454dfac6d5: [read]
EOF

taxii-cli sync data-config.yaml

TAXII 1.x Setup

# Copy template and edit
cp examples/data-config/full.yaml data-config.yaml
# Edit data-config.yaml with your services, collections, accounts

# Apply configuration
taxii-cli sync data-config.yaml

Cleanup Old Data

# Delete content older than 90 days
taxii-cli content delete \
  --collection threat-intel \
  --begin 1970-01-01T00:00:00Z \
  --end $(date -d '90 days ago' --iso-8601=seconds)Z