Skip to content

import.md

Latest commit

 

History

History
221 lines (153 loc) · 7.01 KB

import.md

File metadata and controls

221 lines (153 loc) · 7.01 KB

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

# TypeScript CLI
idw import .env --owner dev@company.com

# Python CLI
idw-py import .env --owner dev@company.com

# Go CLI
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.

# TypeScript CLI
idw import ./project --all --owner dev@company.com -y

# Python CLI
idw-py import ./project --all --owner dev@company.com -y

# Go CLI
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.

# TypeScript CLI
idw import ./project --min-confidence 0.9 --owner dev@company.com

# Python CLI
idw-py import ./project --min-confidence 0.9 --owner dev@company.com

# Go CLI
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.

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 is encoded as a tag on the imported passport: 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 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
const apiKey = process.env.OPENAI_API_KEY;

// After
import { unlockVault } from '@id-wispera/core';

const vault = await unlockVault(passphrase);
const passport = vault.retrievePassport('openai-key-id');
const apiKey = passport.credentialValue;
# Before
api_key = os.environ["OPENAI_API_KEY"]

# After
from id_wispera.vault import unlock_vault

vault = unlock_vault(passphrase)
passport = vault.get_passport("openai-key-id")
api_key = passport.credential_value
// Before
apiKey := os.Getenv("OPENAI_API_KEY")

// After
v, _ := vault.Load(vaultFile, passphrase)
p := v.GetPassport("openai-key-id")
apiKey := p.CredentialValue

Once all references to process.env / os.environ / os.Getenv are replaced, delete the .env file from your repository and add it to .gitignore.