Getting Started with Dethereal

Watch · 1:07A threat model generated from your repository

This guide walks you through installing the Dethereal plugin, connecting to the Dethernety platform, and creating your first threat model.

Prerequisites

• Claude Code — the Anthropic CLI (claude), VS Code extension, or JetBrains plugin
• Node.js 20 or later — required for the MCP server; the plugin will not install or start on Node 18. pnpm as well, if you build from source
• A Dethernety platform instance — local (http://localhost:3003) or hosted over HTTPS

Installation

From the Plugin Marketplace (Recommended)

Add the Dethernety marketplace and install the plugin:

/plugin marketplace add dether-net/claude-plugins
/plugin install dethereal@dether.net

Or via CLI:

claude plugin install dethereal@dether.net

Set the platform URL as an environment variable:

export DETHERNETY_URL=https://dethernety.example.com

For Team Projects

Add to your project's .claude/settings.json so the plugin is available to all team members:

{
  "extraKnownMarketplaces": {
    "dether.net": {
      "source": { "source": "github", "repo": "dether-net/claude-plugins" }
    }
  },
  "enabledPlugins": {
    "dethereal@dether.net": true
  }
}

Team members get prompted to install when they trust the project folder.

From Source (Contributors)

If you're developing from a clone of dether-net/dethernety-oss, run these from the repository root after pnpm install:

# Build the plugin
pnpm --filter "@dether.net/dethereal..." build

# Load it locally
claude --plugin-dir apps/dethereal

Configuration

DETHERNETY_URL must use HTTPS unless the host is localhost, 127.0.0.1, or ::1. Plain http:// to any other host — a self-hosted instance on an internal address, for example — is rejected at startup with a configuration error:

DETHERNETY_URL must use HTTPS for non-localhost connections. HTTP is only permitted for localhost, 127.0.0.1, and ::1.

The MCP server exits rather than starting, so inside Claude Code this looks like the Dethereal tools simply not being there. If your commands have vanished, check the scheme first. Put a TLS-terminating proxy in front of a remote instance, or reach it over an SSH tunnel to localhost.

In no-auth mode the platform runs with authentication disabled (ENABLE_NOAUTH=true), and Dethereal detects this automatically.

Your First Session

When you start Claude Code with the plugin loaded and no models tracked yet, you'll see an orientation message:

Dethereal threat modeling plugin is active.

  /dethereal:create   -- Create or import your first threat model
  /dethereal:status   -- Check connection and auth status
  /dethereal:help     -- See all available commands

  Or just describe your system in natural language:
  "I have a React frontend talking to a Go API with a PostgreSQL database"

That last block is not decoration. You do not have to start with a command — describing your system in plain language is a first-class entry point, and the plugin turns the description into a model.

If the plugin can't reach a platform, one more line follows:

  Platform: not connected (run /dethereal:login to connect)

You'll see it when DETHERNETY_URL is unset and nothing is answering on http://localhost:3003. It is a hint, not a blocker — you can create and enrich a model entirely offline, and connect later.

Once you have models, this orientation is replaced by a short resume hint. With a single model it names the model, its quality score, and its workflow state; with several it gives the count and points you at /dethereal:status.

Checking Connection Status

Run /dethereal:status to verify everything is connected:

Dethernety Connection Status
─────────────────────────────────────────
Platform URL:  https://dethernety.example.com
Auth status:   Not authenticated — run /dethereal:login
─────────────────────────────────────────

No local models found. Run /dethereal:create to get started.

Authentication

Run /dethereal:login to authenticate with the platform. This opens your browser to the login page:

> /dethereal:login

Opening browser for authentication...

Authenticated successfully.
Platform:     https://dethernety.example.com
User:         user@example.com
Token valid:  60 minutes remaining

How Authentication Works

• OAuth 2.0 with PKCE — secure browser-based login, no passwords in the terminal
• Local session — the plugin's MCP server keeps your session under ~/.dethernety/ in your home directory, keyed by platform URL. The tokens stay inside the server: no tool returns them, and the commands check your session through the server rather than by reading that directory
• Auto-refresh — an expired session is refreshed transparently on the next command when a valid refresh token exists
• Desktop browser required — sign-in opens the browser on the machine the plugin runs on, and there is no fallback yet. Over SSH or in a headless container, /dethereal:login fails (Sign-in needs a desktop browser on this machine) or times out waiting for the browser; run it where a browser is available
• Auth-disabled mode — if the platform has auth disabled (no-auth), all tools work without login

Token Security

• Never commit ~/.dethernety/ to version control, and never copy its token file between machines by hand — sign in on each machine instead
• Tokens are specific to each platform URL — switching instances requires separate auth
• Use /dethereal:login to re-authenticate if your session expires
• Signing out through the plugin deletes the local session only; it does not revoke it at the identity provider, and signing out of the platform's web interface does not necessarily end it either. A session copied elsewhere stays valid until its refresh token expires, unless an identity-provider administrator revokes it

Creating Your First Model

There are four ways to create a model. For your first time, describing your system in natural language is the easiest:

Option 1: Describe Your System (Recommended)

> /dethereal:create a web application with a React frontend served by nginx,
  a Node.js API backend, a PostgreSQL database, and user authentication via OAuth

The plugin will:

1. Ask about your most valuable assets (crown jewels)
2. Ask about compliance requirements
3. Identify components and trust boundaries from your description
4. Present everything for your confirmation before writing files

Option 2: Start From a Template

> /dethereal:create template web_app

Available templates: web_app, api_service, microservices.

Two further example models exist — simple (the tool's default) and database — but /dethereal:create deliberately offers only the three above. Those two are minimal, one- and two-component skeletons; they are reachable through the get_example_models tool and are useful as schema references, not as a starting point for a real model.

Option 3: Import From Infrastructure Files

> /dethereal:create from ./infrastructure/

Point it at a directory containing Terraform, Kubernetes manifests, Dockerfiles, or other infrastructure definitions. The plugin's discovery agent scans the files and builds a model from what it finds.

Option 4: Pull From the Platform

> /dethereal:create pull

Lists models on the platform and exports one to local files for enrichment.

What Gets Created

After creating a model, you'll have a directory structure like this:

./threat-models/my-web-app/
├── manifest.json          # Model metadata (name, description, modules)
├── structure.json         # Boundary and component hierarchy
├── dataflows.json         # Data flow connections
├── data-items.json        # Data classifications (empty initially)
├── README.md              # Auto-generated summary
├── .dethereal/            # Workflow metadata (per-model)
│   ├── state.json         # Current workflow state
│   ├── scope.json         # Scope definition (crown jewels, compliance)
│   └── control-audit.log  # Append-only ledger of shared-ownership decisions
│                          # (created on first /dethereal:enrich --focus controls; commit)
├── attributes/            # Security attributes (populated during enrichment)
│   ├── boundaries/
│   ├── components/
│   ├── dataFlows/
│   └── dataItems/
└── controls/              # Per-Control library files (created when first Control
    └── ...                # is referenced by an element; one file per Control)

The plugin also creates a project-level registry at .dethernety/models.json that tracks all local models.

The Model Files

• manifest.json — model metadata: name, description, which modules it uses
• structure.json — the hierarchy of trust boundaries and components with visual coordinates
• dataflows.json — directed connections between components (who talks to whom)
• data-items.json — what sensitive data flows carry (PII, credentials, etc.)
• attributes/ — per-element security properties (authentication, encryption, logging, etc.)

These are plain JSON files that work well with git — you can diff them, review them in PRs, and track changes over time.

The Metadata Directory

The .dethereal/ directory inside each model holds workflow state:

• state.json — where you are in the modeling process (6 states from INITIALIZED to REVIEWED)
• scope.json — what you said about the system's crown jewels, compliance requirements, and trust assumptions
• quality.json — quality score cache (created after first quality check)
• sync.json — sync metadata (created after first platform push/pull)

Example Walkthrough

Here's a complete first-model session:

> /dethereal:create I have a React SPA, a Node.js API, and PostgreSQL

I'll create a threat model for your system. Let me ask a few questions first.

What are the most valuable assets in this system? (These are your "crown jewels"
— the data or capabilities an attacker would target.)

> User account data and session tokens

Any compliance requirements? (e.g., SOC2, HIPAA, GDPR, PCI-DSS)

> SOC2

What do you explicitly trust? (e.g., cloud provider infrastructure, corporate VPN)

> AWS infrastructure

Here's what I've identified:

Components:
  1. [PROCESS] React SPA — in DMZ
  2. [PROCESS] Node.js API — in Internal Network
  3. [STORE] PostgreSQL — in Data Tier
  4. [EXTERNAL_ENTITY] End Users — in Internet Zone

Boundaries:
  Internet Zone / DMZ / Internal Network / Data Tier

Data Flows:
  1. End Users → React SPA: HTTPS requests
  2. React SPA → Node.js API: Internal API calls
  3. Node.js API → PostgreSQL: SQL queries

Confirm or adjust?

> confirm

[done] Model "My Web App" created with 4 components, 3 data flows. Quality: 28/100.
[next] /dethereal:discover (scan codebase for additional infrastructure)

What to Do Next

After creating your model, you have two paths:

The Guided Workflow (Recommended)

Run /dethereal:threat-model to walk through all 11 steps — from discovery and classification through enrichment, validation, and platform sync. This is the most thorough approach and is recommended for new models. See The 11-Step Guided Workflow.

Individual Commands

Use individual commands to work on specific aspects:

• /dethereal:discover — scan your codebase for infrastructure components the description missed
• /dethereal:classify — assign classes to components (enables security analysis)
• /dethereal:enrich — add security attributes (authentication, encryption, logging)
• /dethereal:review — check model quality and get recommendations

See the Command Reference for all available commands, or run /dethereal:help for context-aware suggestions.

Version Control

Since threat models are plain JSON files, commit them alongside your source code:

git add threat-models/ .dethernety/models.json
git commit -m "feat: initial threat model for web application"

What to gitignore: per-user sync state, discovery provenance, and a few transient working files and backups. Copy the full list from What to Commit — and use its per-file rules rather than ignoring the whole .dethereal/ directory.

Token storage (~/.dethernety/) is in your home directory, outside the repository — no gitignore entry needed.

See Sync and Version Control for the full version control workflow.

Next: The 11-Step Guided Workflow — walk through the complete modeling process