Documentation

Everything you need to know about StackDex — your infrastructure single source of truth.

What is StackDex?

StackDex is a Configuration Management Database (CMDB) that helps you document, organize, and understand your infrastructure. It provides a centralized inventory of assets, their relationships, credentials, and people — all with zero-knowledge encryption for secrets.

Core Features

Asset Management

Register servers, databases, APIs, network devices, and any other infrastructure component. Organize by type, category, status, and tags. Track ownership and metadata.

Relationship Mapping

Define dependencies between assets. Visualize your infrastructure topology with interactive graphs. Understand impact chains for incident response.

Credential Vault

Store passwords, API keys, SSH keys, and other secrets with client-side AES-256-GCM encryption. The backend never sees plaintext secrets. Granular contact sharing built in.

Topology Graph

Interactive network graph that visualizes your entire infrastructure. Explore dependencies, trace impact paths, and identify single points of failure.

Traceability

Full impact analysis. From a contact, trace which credentials they have, which accesses those credentials use, and which assets are affected. Audit logs track every change.

Access Control

Role-based access control (Owner, Admin, Editor, Viewer). Workspace-scoped permissions. Invite members and manage roles from the workspace dashboard.

Getting Started

1. Create an account

2. Create a workspace

Workspaces isolate your infrastructure environments (e.g., Production, Staging, Development). Each workspace has its own assets, credentials, members, and encryption keys.

3. Add assets

Start by registering your infrastructure components — servers, databases, APIs, network gear. Categorize by type, add tags, assign owners, and link to projects.

4. Define relationships

Connect assets to show dependencies. For example: "API Server A depends on Database B". View the topology graph to visualize your entire infrastructure.

5. Add credentials

For each asset access method (SSH, HTTP, database, API key), add credentials with encrypted secrets. Set a workspace passphrase — this is the only key that can decrypt your secrets.

6. Manage contacts & trace

Attach contacts to credentials to track who has access to what. Use the traceability features to answer questions like "Which assets can John access?" or "Who has the production database password?"

Credential Encryption

StackDex implements zero-knowledge client-side encryption. Your secrets are encrypted in your browser before they ever reach the server. The backend stores only ciphertext — it never has the key, never sees plaintext, and can never decrypt your secrets.

Encryption Algorithm

AES-256-GCM (Galois/Counter Mode) - Key derivation: PBKDF2 with SHA-256, 600,000 iterations - Key size: 256 bits - IV: 12 bytes, randomly generated per encryption - Authentication tag: 16 bytes (GCM provides authenticated encryption)

How It Works

1. Passphrase → Encryption Key

When you set a workspace passphrase, your browser generates a cryptographic salt (16 random bytes) and derives a 256-bit AES key using PBKDF2 with 600,000 iterations. The salt is stored alongside the encrypted data so the same key can be re-derived from your passphrase later. The derived AES key is held in browser memory only — it is never written to disk or storage. You only need to enter your passphrase once per page load.

2. Encryption (Storing a Secret)

When you save a credential, the browser generates a fresh 12-byte random IV (initialization vector). It encrypts the plaintext using AES-256-GCM with your derived key and the random IV. The output is a binary blob containing ciphertext + GCM authentication tag (16 bytes). The browser sends only the base64-encoded ciphertext and the IV (packaged in encryption_metadata) to the server. The plaintext and the key never leave your browser.

3. Decryption (Viewing a Secret)

To view a credential, the browser fetches the ciphertext and IV from the server (only accessible to authorized users via RBAC). It retrieves the derived AES key from browser memory (or re-derives it from your passphrase if needed). Using the stored IV, it decrypts the ciphertext with AES-256-GCM. GCM automatically verifies the authentication tag — if the ciphertext was tampered with or the wrong key is used, decryption fails immediately.

4. Passphrase Validation (Blind Challenge)

To verify your passphrase is correct without sending the key to the server, the browser encrypts the fixed string "stackdex" using AES-256-GCM with a random IV and stores the result on the server as a challenge token. On subsequent logins, the browser fetches this token, decrypts it locally, and checks if the result is "stackdex". If decryption succeeds, the passphrase is correct. If it fails (GCM authentication fails or the result is garbage), the passphrase is wrong. The server never sees the key or performs any comparison.

Security Properties

Zero-knowledge: The server stores only encrypted blobs. A server breach or database dump yields only ciphertext, never plaintext secrets.

Forward secrecy via passphrase reset: If a passphrase is compromised, an admin can reset it, which destroys all encrypted payloads. New credentials must be re-created under the new passphrase.

Authenticated encryption: AES-256-GCM provides both confidentiality and integrity. Any tampering with the ciphertext is detected upon decryption.

Key derivation hardening: PBKDF2 with 600,000 iterations slows down brute-force attacks against weak passphrases by a factor of 600,000.

Unique IV per encryption: Every encryption uses a fresh random IV, ensuring the same plaintext encrypted twice produces different ciphertext.

Key Management Summary

Item	Stored Where	Notes
AES key (derived)	Browser localStorage (per workspace)	Never sent to server. Derived from passphrase via PBKDF2.
Salt	Server (`encryption_metadata`)	Stored alongside ciphertext. Required for key re-derivation.
IV	Server (`encryption_metadata`)	Random per encryption. Required for decryption.
Passphrase	Never stored	Entered by user per session. Derives the AES key.

Glossary

Workspace

An isolated environment containing its own assets, credentials, members, and encryption keys. Typically maps to a project, team, or environment (prod/staging/dev).

Asset

Any infrastructure component — server, database, API, network device, container, or service. Assets have types, statuses, tags, and optional ownership.

Access

A method of connecting to an asset (SSH, RDP, HTTP, database connection, API endpoint). An access belongs to one asset and can have multiple credentials.

Credential

An encrypted secret (password, API key, SSH key) associated with an access. Encrypted client-side with AES-256-GCM. Can be shared with multiple contacts.

Contact

A person or team associated with credentials. Contacts can be attached to multiple credentials, enabling traceability (who has access to what).

Relationship

A typed connection between two assets (e.g., "depends on", "connects to"). Relationships form the topology graph of your infrastructure.