Skip to main content

​
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:
  1. Single file — parse a specific file (.env, .json, or generic) for credentials.
  2. Directory scan (--all) — recursively scan a directory and import everything found.
  3. 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

idw import .env --owner dev@company.com
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. 
idw import ./project --all --owner dev@company.com -y
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. 
idw import ./project --min-confidence 0.9 --owner dev@company.com

​
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 —> OpenAI
    • sk-ant- prefix —> Anthropic
    • AKIA prefix —> AWS
    • ghp_ / 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.
LevelRangeExamples
High>= 0.9OpenAI keys (sk-...), AWS keys (AKIA...), GitHub tokens (ghp_...)
Medium0.7-0.9Generic API keys, connection strings, base64-encoded tokens
Low< 0.7Possible secrets, high-entropy strings, base64 blobs
Confidence is encoded as a tag on the imported passport: confidence-high, confidence-medium, or confidence-low.

​
Supported File Types

File TypeParsing Strategy
.envLine-by-line KEY=VALUE parsing; keys containing key, secret, token, password, or api are flagged
.jsonRecursive key scanning; string values checked against known patterns
All othersRegex-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

OptionDescription
--allImport 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-nameAuto-generate passport names from detection pattern
-y, --yesSkip 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 dev@company.com

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).
Each imported passport can then be viewed, shared, delegated, or managed through the standard ID Wispera commands: 
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: 
idw import .env --owner dev@company.com -y
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;
After — reading from the ID Wispera vault: 
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

Passport model

Understand the data structure behind every imported credential.

Locations registry

Register where credentials are deployed and used.

Security architecture

Learn how the vault encrypts and protects your secrets.