claudetools/docs/api/credentials/CREDENTIAL_SCANNER_QUICK_REF.md

Credential Scanner Quick Reference

Module: api/utils/credential_scanner Purpose: Import credentials from files to database with auto-encryption

---

Quick Start

from api.database import SessionLocal
from api.utils.credential_scanner import scan_and_import_credentials

db = SessionLocal()
try:
    results = scan_and_import_credentials(
        base_path="C:/Projects/MyClient",
        db=db,
        client_id="uuid-here"  # Optional
    )
    print(f"Imported: {results['credentials_imported']}")
finally:
    db.close()

---

Functions

1. scan_for_credential_files(base_path)

Find all credential files in directory tree.

Returns: List[str] - File paths

Finds:

• credentials.md, credentials.txt
• passwords.md, passwords.txt
• .env, .env.local, .env.production
• secrets.md, auth.md

---

2. parse_credential_file(file_path)

Parse credentials from a file.

Returns: List[Dict] - Credential dictionaries

Example output:

[
    {
        "service_name": "Gitea Admin",
        "credential_type": "password",
        "username": "admin",
        "password": "SecurePass123!"
    },
    ...
]

---

3. import_credentials_to_db(db, credentials, client_id=None, user_id="system_import")

Import credentials with auto-encryption.

Returns: int - Count of imported credentials

Features:

• Auto-encrypts sensitive fields (AES-256-GCM)
• Creates audit log entries
• Never logs plaintext values
• Continues on errors

---

4. scan_and_import_credentials(base_path, db, client_id=None, user_id="system_import")

Complete workflow in one call.

Returns: Dict[str, int]

{
    "files_found": 3,
    "credentials_parsed": 8,
    "credentials_imported": 8
}

---

File Formats

Markdown (.md)

## Service Name
Username: admin
Password: secret123
API Key: sk-1234567890
URL: https://example.com
Notes: Additional info

Environment (.env)

DATABASE_URL=mysql://user:pass@host/db
API_KEY=sk-1234567890
SECRET_TOKEN=abc123def456

Text (.txt)

Same as Markdown format

---

Credential Types Auto-Detected

Value Pattern	Type	Field
sk-*	api_key	api_key
ghp_*	api_key	api_key
mysql://...	connection_string	connection_string
-----BEGIN...	ssh_key	password
JWT (3 parts)	jwt	token
Default	password	password

---

Security

Encryption: AES-256-GCM via credential_service Audit: Every import logged to credential_audit_log Logging: Never logs plaintext credentials

---

Command Line

# Preview
python example_credential_import.py /path --preview

# Import
python example_credential_import.py /path --client-id "uuid"

---

Common Workflows

Import from Client Directory

db = SessionLocal()
try:
    results = scan_and_import_credentials(
        "C:/Projects/ClientA",
        db,
        client_id="client-uuid"
    )
finally:
    db.close()

Preview Before Import

files = scan_for_credential_files("/path")
for f in files:
    creds = parse_credential_file(f)
    print(f"{f}: {len(creds)} credentials")

Import with Error Handling

files = scan_for_credential_files("/path")
for file_path in files:
    try:
        creds = parse_credential_file(file_path)
        count = import_credentials_to_db(db, creds)
        print(f"✓ {count} from {file_path}")
    except Exception as e:
        print(f"✗ Failed: {e}")

---

Testing

python test_credential_scanner.py
# All 5 tests should pass

---

Documentation

• Full Guide: CREDENTIAL_SCANNER_GUIDE.md
• Summary: CREDENTIAL_SCANNER_SUMMARY.md
• Examples: example_credential_import.py
• Tests: test_credential_scanner.py

---

Troubleshooting

No files found?

• Check base_path exists
• Verify file names match patterns
• Ensure not in excluded dirs (.git, node_modules)

Parsing errors?

• Verify file format (headers, key:value pairs)
• Check UTF-8 encoding
• Ensure recognized key names

Import fails?

• Check database connection
• Verify ENCRYPTION_KEY set
• Check client_id exists (if provided)

---

Quick Help: See CREDENTIAL_SCANNER_GUIDE.md for complete documentation