CUPELON

Documentation

Prerequisites

  • Ubuntu 22.04+, Debian 11+, or RHEL 8+ server (2+ CPU cores, 4GB+ RAM)
  • Public DNS A record pointing to your server (for webhook delivery and auto-HTTPS)
  • Azure AD / Entra ID app registration with Graph API permissions (M365) or Google service account (Workspace)
  • Cupelon license key and install token (from your dashboard)

1. Purchase a Plan

Choose a plan on the pricing page, complete checkout, and your credentials will be generated instantly. Annual plans receive a 30-day provisional license immediately so you can install while ACH/wire payment clears.

2. Copy Your Install Command

After checkout, your dashboard will show a personalized one-line install command with your license key and install token already embedded. Copy it and run it on your server.

Example (your dashboard provides the real command)

curl -sL https://install.cupelon.com/setup | sudo bash -s -- --token=*** --license=***

What the installer does:

  1. Detects your OS and installs dependencies
  2. Prompts for Azure AD credentials (tenant ID, client ID, secret/cert) or Google service account
  3. Prompts for your public domain name (for webhooks + auto-HTTPS)
  4. Generates secure passwords and configures the application
  5. Starts all services and runs database migrations
  6. Validates API connectivity to your email platform
  7. Creates webhook subscriptions for all licensed mailboxes
  8. Prints your dashboard URL and admin credentials

3. Azure AD Configuration (M365)

Your Entra ID app registration needs these Graph API application permissions:

PermissionPurpose
Mail.ReadRead mail in all mailboxes for threat analysis
Mail.ReadWriteInject warning banners and training panels into messages
User.Read.AllEnumerate mailboxes for webhook subscription creation
MailboxSettings.ReadCheck mailbox configuration

GCC High Tenants

Ensure your app registration is in the Azure Government portal (portal.azure.us) and set CUPELON_ENVIRONMENT=gcchigh. The installer will prompt you for this during setup.

Certificate Authentication

For environments requiring certificate-based authentication, use an X.509 certificate instead of a client secret. The installer will prompt for your certificate path and thumbprint during setup.

3b. Google Workspace Configuration

For Google Workspace deployments, configure a service account with domain-wide delegation. The installer will prompt for your service account credentials and notification settings during setup.

What You'll Need

  • Google Cloud service account JSON key file
  • Domain-wide delegation enabled for the service account
  • Delegated admin email address
  • Google Cloud project with Pub/Sub API enabled

4. Verify Installation

After the installer completes, visit your domain to see the Cupelon dashboard. Check service health:

curl https://your-domain/health      # Should return {"status":"ok"}
cupelon status                        # Check all services are running

Network Requirements

PortDirectionNotes
443InboundHTTPS — dashboard + webhook receiver. TLS certificates provisioned automatically.
80InboundHTTP — certificate provisioning only, redirects to HTTPS

All other ports are internal and not exposed. Outbound traffic is limited to your email platform's API endpoints (Microsoft Graph or Google Workspace).

Configuration Reference

Key settings managed through the installer and dashboard. Most can be changed at runtime via the dashboard config page without restarting services.

Environmentdefault: gcchigh

GCC High or commercial — determines API endpoints

Certificate Authdefault: Off

Use X.509 certificate authentication instead of client secrets

Auth Modedefault: API Key

API key or Entra ID — dashboard authentication method

Tenant IDdefault: (required)

Azure AD tenant ID or Google Workspace domain

Client IDdefault: (required)

Azure AD application client ID

Domaindefault: (required)

Public domain name for webhooks and HTTPS

License Keydefault: (required)

License key from your dashboard

Platformdefault: M365

Microsoft 365 or Google Workspace

Log Leveldefault: INFO

Logging verbosity (DEBUG, INFO, WARNING, ERROR)

Banner Thresholds

Adjust when banners are triggered. All thresholds can be changed in the dashboard without restarting services.

SettingDefaultDescription
Yellow threshold2 usersUnique users who must flag a sender before caution banner appears
Red threshold3 usersUnique users for high-threat banner (requires zero rescues)
Campaign sensitivity65%Content similarity threshold for campaign match (orange banner)
Nuisance threshold2 flags + 1 rescueMixed signals required for nuisance (blue) banner

Air-Gap Installation

For environments without internet access, contact support@cupelon.com for an offline installation package. The package includes everything needed to deploy on an air-gapped server — just transfer it via USB or secure file transfer and run the included installer.

Updates

Cupelon checks for updates automatically and performs zero-downtime upgrades in the background.

  • Automatic: Updates are applied automatically with zero downtime — no action needed
  • Manual: Run cupelon update to check for and apply updates on demand
  • Disable auto-updates: Configurable in the dashboard settings
  • Air-gap: Transfer the update package via USB and run the offline updater

Troubleshooting

Webhooks not firing

  • Verify your server is reachable on port 443 from the internet
  • Check that your DNS A record points to the correct IP
  • Ensure your configured domain matches your DNS record exactly
  • Webhook subscriptions auto-renew — check the dashboard for renewal status

Banners not appearing in emails

  • Verify Mail.ReadWrite permission is granted and admin-consented
  • Check banner thresholds — default requires 2+ unique users to flag a sender
  • Check if the domain is on your safe domain allowlist
  • Review the audit log in the dashboard for banner events and errors

License validation errors

  • Verify your tenant ID matches the one used during purchase
  • Check license expiration — expired licenses get a 7-day grace period
  • Ensure the license key is set correctly (no extra whitespace or line breaks)

GCC High authentication failures

  • Verify the environment is set to GCC High
  • Ensure app registration is in portal.azure.us, not portal.azure.com
  • GCC High uses different API endpoints — check the dashboard logs for connection errors

Need more help?

Contact support@cupelon.com with your application logs: run cupelon logs > cupelon-logs.txt and attach the file to your support request.