Scan & Import Guide
ID Wispera can scan files, directories, and known credential locations to detect secrets, then import them as governed passports in the vault. This guide covers the three import modes and the full scan-review-import workflow.
Overview
The import command supports three modes:
- Single file — parse a specific file (
.env, .json, or generic) for credentials.
- Directory scan (
--all) — recursively scan a directory and import everything found.
- Confidence threshold (
--min-confidence) — scan a directory but only import detections above a confidence score.
Each detected credential becomes a passport with auto-generated metadata including the source file, line number, confidence score, and detection pattern.
Import Modes
Import from a Single File
The CLI parses the file based on its extension:
.env files are parsed as KEY=VALUE pairs..json files are recursively scanned for keys named key, secret, token, password, or api.- All other files use regex-based pattern detection.
Scan and Import All
Recursively scan a directory and import every detected credential.
The -y flag skips the interactive confirmation prompt. Without it, the CLI displays each detection and asks you to confirm before importing.
Import by Confidence Level
Only import detections that meet a minimum confidence threshold.
Import from OpenClaw
Scan the ~/.openclaw/ directory structure for all managed credentials (API keys, bot tokens, OAuth tokens, session keys).
idw import --format openclaw
This mode discovers credentials across the OpenClaw directory tree including WhatsApp sessions, LLM auth profiles, OAuth tokens, channel bot tokens, and gateway tokens.
What Gets Imported
For each detected credential, a passport is created with:
- Name:
{pattern} in {filename} (e.g., “OpenAI API Key in .env”)
- Tags:
imported, scan, confidence level tag, source filename
- Notes: Full file path, line number, confidence score, detection pattern
- Platform: Auto-guessed from the credential value:
sk- prefix —> OpenAIsk-ant- prefix —> AnthropicAKIA prefix —> AWSghp_ / gho_ prefix —> GitHub- Other patterns —> custom
Confidence Levels
The detection engine assigns a confidence score to each finding based on the pattern strength and context.
| Level | Range | Examples |
|---|
| High | >= 0.9 | OpenAI keys (sk-...), AWS keys (AKIA...), GitHub tokens (ghp_...) |
| Medium | 0.7-0.9 | Generic API keys, connection strings, base64-encoded tokens |
| Low | < 0.7 | Possible secrets, high-entropy strings, base64 blobs |
confidence-high, confidence-medium, or confidence-low.
Supported File Types
| File Type | Parsing Strategy |
|---|
.env | Line-by-line KEY=VALUE parsing; keys containing key, secret, token, password, or api are flagged |
.json | Recursive key scanning; string values checked against known patterns |
| All others | Regex-based detection using known credential patterns (API key prefixes, private key headers, etc.) |
Directories named .git, node_modules, __pycache__, .venv, vendor, dist, and build are automatically skipped. Binary files and files larger than 1 MB are also skipped.
Options Reference
| Option | Description |
|---|
--all | Import all detected credentials without a confidence filter |
--min-confidence <n> | Minimum confidence threshold (0.0 to 1.0) |
--format <fmt> | Import format: env, json, openclaw |
--owner <email> | Human owner email (required for passport creation) |
--auto-name | Auto-generate passport names from detection pattern |
-y, --yes | Skip the interactive confirmation prompt |
-p, --path <path> | Custom vault path (default: ~/.id-wispera) |
Workflow: Scan, Review, Import
A typical import session follows three steps.
Step 1: Scan
$ idw import ./my-project --min-confidence 0.8 --owner [email protected]
Scanning for Credentials
──────────────────────────────
Target: /home/dev/my-project
Mode: min confidence 0.8
Scanned 247 files.
Found 3 Credential(s)
# File Line Pattern Confidence Value (masked)
─────────────────────────────────────────────────────────────────────
1 .env 3 OpenAI API Key 0.98 sk-proj-****...****7xQ2
2 .env 7 AWS Access Key 0.95 AKIA****...****ODNN
3 config.json 12 GitHub PAT 0.91 ghp_****...****a3Bf
Step 2: Review
Without the -y flag, the CLI prompts for confirmation:
Import 3 credential(s) as passports? [y/N] y
Step 3: Import
Vault passphrase: ********
Imported: OpenAI API Key in .env (a1b2c3d4...)
Imported: AWS Access Key in .env (e5f6g7h8...)
Imported: GitHub PAT in config.json (i9j0k1l2...)
Successfully imported 3/3 credential(s).
idw list --tag imported
idw show a1b2c3d4
Migrating from .env Files
For teams moving from .env-based secret management to ID Wispera, the quickest migration path is:
After importing, update your application code to retrieve credentials from the vault SDK instead of process.env.
Before — reading from environment variables:
const apiKey = process.env.OPENAI_API_KEY;
import { unlockVault } from '@id-wispera/core';
const vault = await unlockVault(passphrase);
const passport = vault.retrievePassport('openai-key-id');
const apiKey = passport.credentialValue;
Once all references are replaced, delete the .env file from your repository and add it to .gitignore.
Next Steps
