Documentation

Quick Start

brew install butterfly-cli

butterfly login

# Show backup status
butterfly status

# List all backups
butterfly list

# Trigger a new backup
butterfly backup

# Compare two backups
butterfly diff <backup1-id> <backup2-id>

# Export to Terraform
butterfly export terraform <backup-id>

Authentication Methods

butterfly login

butterfly login --api-key sk_xxxxx

How OAuth Device Flow Works

1. 1

   Run butterfly login

   CLI generates a unique device code

2. 2

   Browser opens automatically

   You are taken to the login page with your device code

3. 3

   Complete authentication

   Choose your login method (Google, GitHub, Email, etc.)

4. 4

   Token returned to CLI

   You are logged in -- no manual copy/paste needed

Token Storage

Multi-Provider AI Support

Bring your own API key and choose your preferred AI provider:

How It Works

• Auto-analysis on node selection -- Click any user, group, app, or policy in the topology to trigger an automatic security assessment
• Quick action buttons -- Use preset prompts like "Risks?", "Over-provisioned?", and "Improvements?" for instant analysis
• Conversational follow-ups -- Ask follow-up questions about the selected entity for deeper investigation

Example Queries

Features

Capabilities

• Visualize connections between users, groups, apps, and policies in a single graph
• Click any node to see details, metadata, and trigger AI security analysis
• Zoom, pan, and search within the graph to find specific resources
• Multiple relationship types -- member_of, assigned_to, governed_by, authenticates_with, and more

Relationship Types

What We Detect

Remediation Features

• Step-by-step instructions -- Each finding includes detailed remediation steps specific to your identity provider configuration
• Priority-based triage -- Findings are ranked by severity (critical, high, medium, low) so you can address the most important issues first
• Framework mapping -- Each remediation links back to the specific compliance control it satisfies (SOC 2, HIPAA, PCI DSS, etc.)

How It Works

What Gets Detected

10 Simulation Types

Simulation Results Include

• Risk score (0-100) -- Overall severity of the simulated incident
• Blast radius -- Exact count of affected users, apps, and policies
• Cascade effects -- Secondary and tertiary impacts traced through your topology
• Mitigation steps -- Actionable recommendations to reduce risk

How Backup Works

1. 1

   Authentication

   We generate a short-lived OAuth access token using your private key

2. 2

   Data Collection

   We call your provider's APIs to fetch each resource type, respecting rate limits

3. 3

   Snapshot Creation

   All data is combined into a versioned snapshot with SHA-256 hashes for integrity

4. 4

   Secure Storage

   The snapshot is encrypted and stored in your isolated storage bucket

Configuring a Schedule

You can configure scheduled backups from the Connections page by clicking on the schedule display for any connection.

1. Go to Dashboard → Connections
2. Click on the schedule text (e.g., "Manual" or "Daily at 02:00")
3. Toggle "Enable scheduled backups"
4. Select your preferred frequency, time, and timezone
5. Click "Save Schedule"

Schedule Options

Failure Handling

If a scheduled backup fails, the system will automatically:

• Increment a failure counter and log the error
• Continue scheduling future backups
• After 3 consecutive failures, pause scheduling for 24 hours
• Display warnings in the schedule modal

To resume after a pause, simply re-save the schedule configuration. This will clear the failure count and immediately reschedule the next backup.

Best Practices

• Schedule backups during off-peak hours to minimize impact on API rate limits
• Use daily backups for most organizations; hourly is rarely necessary
• Monitor the schedule history to ensure backups are completing successfully
• Consider your data retention needs when choosing a backup frequency

Restore Modes

Restore Behavior

Restore Support by Provider

Safe Restore Workflow

What You Can See

How to Compare

1. Navigate to Dashboard → Diff
2. Select your connection
3. Choose two backup snapshots to compare
4. Review the summary of added, modified, and removed resources
5. Click into any resource to see field-level changes

Features

• Preview mode -- See exactly what would change before applying any modifications
• Selective sync -- Choose specific resource types to sync (e.g., only policies and groups)
• Multi-environment support -- Sync across dev, staging, and production environments

What's Backed Up

Connector Builder Support

Butterfly Security fully supports Okta Workflows Connector Builder, backing up your custom connector projects:

Setup Requirements

To backup Workflows, you need a dedicated service account with specific configuration:

What Gets Restored

Restore Modes

How Restore Works

Selective Restore

You can choose exactly which items to restore:

• Individual folders — Select specific folders to restore
• Individual connectors — Choose which Connector Builder projects to restore
• Skip table data — Restore schemas only, without row data

Note: Individual flows cannot be restored separately due to the flopack format — entire folders are restored as a unit.

Recommended Backup Schedule

Disaster Recovery Tips

Security Recommendations

• Use OAuth with private key authentication for service access
• Grant only the minimum scopes needed for your backup requirements
• Rotate your OAuth private key periodically (annually at minimum)
• Monitor your provider's audit log for unusual API activity from your backup app

Supported Providers

Terraform export is available for providers with official Terraform providers. Select a provider below for details.

Select a provider above to see available Terraform resources and configuration.

Supported Resources (Okta)

We generate HCL for the following okta/okta resource types:

Step-by-Step Export Guide

# Initialize the provider
terraform init

# Preview what Terraform will do
terraform plan

# Apply changes (be careful!)
terraform apply

Okta Provider Configuration

The generated HCL includes the provider block. You'll need to set these environment variables:

# Required - your Okta org URL
export OKTA_ORG_NAME="your-org"
export OKTA_BASE_URL="oktapreview.com"  # or okta.com

# OAuth 2.0 authentication
export OKTA_API_CLIENT_ID="your-client-id"
export OKTA_API_PRIVATE_KEY_ID="your-key-id"
export OKTA_API_PRIVATE_KEY="path/to/private-key.pem"

Common Use Cases

Supported Platforms

How It Works

Butterfly Security uses OAuth to connect to your Git provider. You authorize access through your provider's login page — no tokens to create, copy, or manage. Your credentials are encrypted and stored securely on our servers.

Step-by-Step Guide

What Gets Exported

Each export creates a timestamped directory with your backup data:

identity-backups/
└── 2025-01-15T10-30-00Z/
    ├── users.json
    ├── groups.json
    ├── applications.json
    ├── policies.json
    ├── authorization-servers.json
    ├── network-zones.json
    └── ...

The commit message includes a summary of what was backed up (e.g., "Backup: 150 users, 25 groups, 12 apps").

Supported Compliance Frameworks

Each framework has specific checks mapped to its control requirements. Click on a framework to view the official requirements:

What We Check

Our compliance engine analyzes your configuration for security best practices across identity, automation, and vault platforms:

Running Compliance Checks

Using Compliance Results

Monitoring Dashboard Overview

The monitoring page gives you a single view of all backup activity across your connections:

Using the Monitoring Dashboard

Backup Status Reference

Each backup shows one of these statuses:

Common Monitoring Scenarios

Retention Options

Connection & Authentication Issues

Backup Issues

Restore Issues