User Personas and Operator Use Cases for DBSurveyor#

DBSurveyor is a security-focused, offline-first database analysis and documentation toolchain designed to serve four distinct user personas with specialized operational requirements. The tool's dual-binary architecture separates data collection from documentation generation, enabling flexible security-aware workflows across different operational contexts—from covert post-compromise database enumeration to enterprise compliance auditing.

Each persona—Red Team Operators, Blue Team Analysts, Database Administrators, and System Administrators—brings unique requirements, threat models, and operational constraints. DBSurveyor addresses these diverse needs through a common two-step workflow (collect schema → generate documentation) while providing persona-specific features, command-line options, and security guarantees.

The tool establishes core security guarantees that apply across all personas: NO NETWORK CALLS (zero external communication after installation), NO TELEMETRY (absolutely no data collection or external reporting), NO CREDENTIALS IN OUTPUTS (database credentials never stored in output files), and AIRGAP COMPATIBLE (full functionality in air-gapped environments). These guarantees form the foundation for trusted operation across adversarial, compliance, and operational contexts.

Core User Personas#

Red Team Operators#

Overview#

Red Team Operators conduct post-compromise database enumeration in contested environments, using compromised credentials to survey target databases without leaving traces. Their operational context requires maximum stealth, minimal footprint, and the ability to exfiltrate intelligence for offline analysis.

Primary Use Cases#

Use Case 1: Covert Database Collection
Red Team operators use DBSurveyor during active engagements to collect database schemas using compromised credentials while avoiding detection by defensive monitoring systems.

Use Case 2: Offline Intelligence Processing
After exfiltration, operators process encrypted survey files offline to generate actionable intelligence, identify privilege escalation opportunities, and highlight tables containing credentials or sensitive data.

Key Requirements#

• Minimal Operational Footprint: Throttle operations with --throttle flag for stealth (configurable delay between operations)
• Secure Transport: AES-GCM-256 encryption via --encrypt flag with random nonce generation and authenticated headers
• Complete Offline Functionality: Air-gapped operation in isolated environments
• Read-Only Operations: SELECT, SHOW, DESCRIBE statements only—no writes, creates, updates, or deletes
• Portable Schema Files: Generate compressed .dbsurveyor.json.zst or encrypted .dbsurveyor.enc files for exfiltration

Operational Workflow#

# 1. Stealth collection with throttling (1000ms delay)
dbsurveyor-collect --throttle 1000 postgres://localhost/db

# 2. Encrypted & compressed output for secure exfiltration
dbsurveyor-collect --encrypt --compress postgres://localhost/db

# 3. Offline analysis after extraction
dbsurveyor generate schema.enc # Prompts for password
dbsurveyor analyze --input schema.json --detailed

Source: CLI Examples

OPSEC Considerations#

The user stories document defines specific OPSEC requirements for Red Team operations:

• No telemetry or external network calls: Enforced at architectural level
• Minimal logging: Logging system implements quiet mode (-q) showing ERROR level only, stripping file names, line numbers, and thread IDs
• Credential sanitization: Database URLs automatically redacted in all error messages (e.g., postgres://user:****@localhost:5432/mydb)
• Memory security: Credentials use zeroize crate to automatically zero sensitive data in memory when dropped
• Connection pooling disabled: Reduces resource footprint and detection signatures
• Randomized query intervals: When rate-limiting active (planned feature)

Blue Team Analysts#

Overview#

Blue Team Analysts audit unknown systems and inherited databases for security assessment, compliance violations, and risk identification. Their work involves comprehensive schema understanding, sensitive data pattern detection, and generating reports for compliance frameworks.

Primary Use Cases#

Use Case 1: Legacy Database Compliance Audit
Analysts audit legacy databases for PII/PCI compliance violations, using field classification algorithms and data value sampling to identify unencrypted sensitive fields.

Use Case 2: SQL Schema Reconstruction (Pro Feature)
Generate complete SQL CREATE statements and ER diagrams for comprehensive documentation, preserving foreign key relationships, constraints, views, and stored procedure signatures.

Key Requirements#

• Comprehensive Schema Analysis: Multiple output formats for different analysis needs (Markdown, HTML, JSON, Mermaid ERD)
• Data Classification: Compliance mode with PII/PCI detection algorithms based on naming patterns and value sampling
• Redaction Controls: Four redaction modes (none, minimal, balanced, conservative) for protecting sensitive data before sharing reports
• Sample Data Collection: Configurable per-table row counts for identifying sensitive information patterns

Operational Workflow#

# 1. Basic collection and documentation
dbsurveyor-collect postgres://user:pass@localhost/db
dbsurveyor generate schema.dbsurveyor.json

# 2. Conservative redaction for maximum privacy
dbsurveyor --redact-mode conservative schema.json

# 3. Detailed security analysis
dbsurveyor analyze schema.json --detailed

# 4. Multiple format generation for different audiences
dbsurveyor --format markdown schema.json
dbsurveyor --format html schema.json
dbsurveyor --format json schema.json

Source: CLI Examples

Feature Requirements#

• JSON analysis format for programmatic security assessment and integration with security tools
• Custom compliance rules via --rules-file compliance.yaml (planned feature)
• Field classification with configurable sample sizes
• Multi-database collection for comprehensive system audits

Database Administrators (DBAs)#

Overview#

Database Administrators require comprehensive documentation and compliance reporting for operational management, change tracking, and professional-grade documentation generation across multiple database platforms.

Primary Use Cases#

Use Case 1: Unknown Schema Discovery
DBAs quickly survey and document unknown database schemas when inheriting environments, identifying table relationships, estimating sizes, and generating connection examples.

Use Case 2: Portable Documentation Artifacts
Create portable, version-control-friendly documentation for team collaboration, including standalone HTML documentation with search functionality and shareable schema browsers.

Key Requirements#

• Professional Documentation: Multiple output formats: Markdown (✅ implemented), HTML (🚧 planned), JSON (✅ implemented), Mermaid ERD (🚧 planned), SQL DDL (🚧 planned)
• Multi-Platform Support: PostgreSQL, MySQL, SQLite, MongoDB, SQL Server support across different operational contexts
• Version Control Integration: Deterministic output with meaningful diffs for tracking schema changes
• Configuration Management: Environment-specific settings via .dbsurveyor.toml configuration files

Operational Workflow#

# 1. Multi-database collection
dbsurveyor-collect --all-databases \
  --exclude-databases postgres,template0 \
  postgres://localhost

# 2. SQL DDL reconstruction for different platforms
dbsurveyor sql schema.json --dialect postgresql --output recreate.sql
dbsurveyor sql schema.json --dialect mysql --output mysql-schema.sql

# 3. Interactive HTML reports with search
dbsurveyor --format html --output full-report.html schema.dbsurveyor.json

# 4. Entity relationship diagrams
dbsurveyor --format mermaid schema.json

Source: CLI Examples

Configuration Needs#

• Custom redaction patterns for sensitive columns
• CI/CD integration for automated schema documentation
• Connection timeouts and query timeouts for different network conditions
• Sample size configuration and output format customization

System Administrators#

Overview#

System Administrators explore inherited or legacy databases with minimal documentation, requiring quick schema understanding, performance management for large databases, and standardized reporting across infrastructure.

Primary Use Cases#

Use Case 1: Multi-Instance Schema Validation
SysAdmins validate schema consistency across multiple database instances (production, staging, development), identifying drift, missing tables, fields, indexes, and constraint inconsistencies.

Use Case 2: Standardized Reporting
Generate standardized reports across all database instances for inventory management, compliance reporting, and integration with monitoring systems.

Key Requirements#

• Quick Schema Understanding: Rapid operational insights for troubleshooting and management
• Large Database Handling: Compression support via --compress flag for managing large schema files
• Connection Testing: Test database access before full collection via dbsurveyor-collect test command
• Database-Specific Features: Support for platform-specific features across PostgreSQL, MySQL, MongoDB, SQL Server

Operational Workflow#

# 1. Simple SQLite example
sqlite3 sample.db << EOF
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    username TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
EOF

dbsurveyor-collect sqlite://sample.db
dbsurveyor generate schema.dbsurveyor.json
cat schema.md

# 2. Quick connection testing
dbsurveyor-collect list # List supported databases
dbsurveyor-collect test postgres://localhost/db

# 3. Verbose troubleshooting
export RUST_LOG=debug
dbsurveyor-collect -vvv postgres://localhost/db

Source: CLI Examples

Infrastructure Features#

• Parallel processing of multiple database connections for efficient multi-instance scanning
• Integration with infrastructure monitoring tools via JSON/CSV exports
• Automated periodic surveys with --schedule flag for cron integration (planned)
• Historical tracking of schema changes for drift detection

Cross-Cutting Operational Concerns#

Secure Credential Management#

All personas require secure credential handling with multiple input methods and zero credential exposure:

Credential Input Methods:

• Environment variables for all connection parameters (recommended)
• Credential files (JSON, YAML) with restricted permissions
• Connection string parsing with credential extraction
• Vault integration: HashiCorp Vault, AWS Secrets Manager (planned)

Security Guarantees:

• Database credentials are never stored, logged, or included in any output files
• Connection strings sanitized in all error messages and logs
• Use read-only database users to minimize blast radius
• Memory-safe credential handling with automatic zeroing

Security Guarantees Across All Personas#

Core security properties that apply universally:

• NO NETWORK CALLS: Complete offline operation after installation, beyond collector connection to target database
• NO TELEMETRY: Zero data collection, usage tracking, or external reporting
• NO CREDENTIALS IN OUTPUTS: Database credentials never appear in any output file
• READ-ONLY OPERATIONS: SELECT/DESCRIBE statements only—no write operations performed
• AIRGAP COMPATIBLE: Full functionality in air-gapped environments
• CONFIGURABLE TIMEOUTS: All connections and queries have configurable timeouts (default: 30 seconds)

Dual-Binary Workflow Architecture#

The separation of collection and documentation generation provides benefits across all personas:

Workflow Steps:

1. Collection Phase (dbsurveyor-collect): Connect to database, extract schema metadata, generate portable .dbsurveyor.json file
2. Documentation Phase (dbsurveyor): Read schema file, generate multiple output formats offline

Benefits:

• Security: Collection in secure environments, documentation generation offline
• Flexibility: Multiple documentation formats from single collection
• Portability: Schema files transferable between environments
• Auditability: Clear separation between data collection and processing

Output Format Selection by Use Case#

Multiple output formats support different operational needs:

Database Platform Support by Persona#

Each persona may prioritize different database platforms based on operational context:

Note: Red Team priorities reflect common target environments in penetration testing engagements.

Configuration and Customization#

All personas customize behavior through multiple mechanisms:

Configuration Methods:

• Command-line options (highest priority)
• Environment variables
• .dbsurveyor.toml configuration files
• Default values (lowest priority)

Common Customizations:

• Connection and query timeouts for network conditions
• Sample size and throttling for operational stealth
• Redaction modes for data sensitivity levels
• Output format selection and customization
• Environment-specific settings (development, production, CI/CD)

Example Configuration File:

[collection]
timeout = 60
throttle = 500
max_connections = 1

[security]
redact_mode = "balanced"
encrypt_output = true

[output]
format = "markdown"

Relevant Code Files#

Related Topics#

• Database Collection Guide: Collection features, options, and database-specific details
• Configuration Guide: Environment variables, CLI options, and configuration file formats
• Output Formats Guide: Schema file formats, documentation generation, and output customization
• Security Features: Encryption, credential protection, and security guarantees
• Architecture Overview: System design, adapter pattern, and component details
• Offensive Security Workflows: Using DBSurveyor in penetration testing engagements
• Compliance Frameworks: Mapping DBSurveyor features to PCI-DSS, GDPR, HIPAA requirements
• CI/CD Integration: Automating schema documentation in continuous integration pipelines