Skip to content

Latest commit

 

History

History
462 lines (357 loc) · 39.4 KB

DATABASE_PENTEST.md

File metadata and controls

462 lines (357 loc) · 39.4 KB

Database Pentesting

Eggsec provides a standalone defense-lab CLI for direct (non-web) security assessment of database servers via the db-pentest feature. Phase 1 (complete 2026-06-12) delivers high-signal checks for authorized lab and defense-validation use only, focused on Postgres (primary) and MySQL (secondary). Phase 2 (executed on main 2026-06-12) adds real MSSQL support via tiberius (gated behind marker db-pentest-mssql-tiberius), docker lab services, a full --real smoke leg, combined web-SQLi + db-pentest example artifacts (db-* + sqli-* side-by-side), qcount cleanup, richer cross-DB dry-run parity, and CLI/smoke/docs updates — all while preserving the Phase 1 safety model. Phase 3 (executed on main 2026-06-12) adds TUI tab (Tab::DbPentest), pipeline ScanProfile::DbRegression, advanced gated checks (--allow-db-pentest-advanced), correlation stub, and evidence bundle export. Phase 4 (complete 2026-06-12) delivers full real advanced reversible test vectors with automatic cleanup, a full correlation engine with scoring/enrichment/timeline (DbCorrelationEngine, DbCorrelationType, DbCorrelatedFinding, DbCorrelationResult), native Stage::DbPentest pipeline stage, evidence bundle v2 with correlation data, and --evidence-bundle CLI flag.

Cleanup & Polish (2026-06-14): Shared URL builders (build_postgres_url, build_mysql_url, build_mongodb_url, build_redis_url) consolidated into db_pentest::utils module. Error handling standardized to anyhow::Result throughout all engine modules. Credential redaction improved for edge cases (no-password, no-scheme, no-colon user strings). 66 unit tests across 8 files.

MCP Registration & Connection Pooling (2026-06-14): SecurityTool implementation for db-pentest is now in tool/implementations/db_pentest.rs with full EnforcementContext enforcement. Engine functions accept optional pool/client references (Option<&PgPool>, Option<&MySqlPool>, Option<&redis::Client>) for connection reuse across check vectors. mod.rs creates shared pools/clients and passes them to engine functions and advanced test vectors, avoiding redundant connections.

This is direct database protocol assessment. The tool performs read-only or safe information_schema/pg_catalog queries against lab instances you explicitly provide. It is not a general-purpose exploitation framework, does not perform unbounded data exfiltration, and makes no changes to the target database state unless you explicitly authorize reversible test actions (Phase 4 real advanced execution).

Feature Gate

Build with --features db-pentest (or --features full).

cargo build --release -p eggsec-cli --features db-pentest

Marker features for additional engines and integrations:

  • db-pentest-mongodb — enables MongoDB engine (adds mongodb driver dep)
  • db-pentest-redis — enables Redis engine (adds redis driver dep)
  • db-pentest-mcp — enables SecurityTool registration for db-pentest in tool/implementations/db_pentest.rs with EnforcementContext enforcement (opt-in after security review)
# With MongoDB support
cargo build --release -p eggsec-cli --features db-pentest,db-pentest-mongodb

# With all db-pentest engines + MCP
cargo build --release -p eggsec-cli --features db-pentest,db-pentest-mongodb,db-pentest-redis,db-pentest-mcp

Runtime requirements:

  • Network access to the lab Postgres (5432), MySQL (3306), MongoDB (27017), or Redis (6379) instance (depending on --type or connection string)
  • Valid credentials for the target lab account (least-privilege recommended)
  • sqlx drivers are included behind the feature (no external psql/mysql binary required)
  • MongoDB driver requires the db-pentest-mongodb marker feature
  • Redis driver requires the db-pentest-redis marker feature

Connection Pooling: Engine functions accept optional pool/client references (Option<&PgPool>, Option<&MySqlPool>, Option<&redis::Client>) for connection reuse. mod.rs creates shared pools/clients and passes them to engine functions and advanced test vectors, avoiding redundant connections when multiple check categories target the same database.

Safety & Scope

  • Use only on database instances you own or are explicitly authorized to assess (lab, authorized defensive validation, hardening regression).
  • Direct protocol access — queries are executed against the DB server itself. All operations are logged in the report (actions_performed, queries_executed).
  • Bounded by design: strict query/time budgets (--max-queries, --max-duration), sampling limits, and redaction of credentials/sensitive values in evidence.
  • Lab DB manifest (--lab-manifest) provides an allowlist of hosts/ports/database name patterns (TOML). It is advisory in ManualPermissive mode (with warnings) and can be enforced more strictly under other profiles.
  • Explicit --allow-db-pentest is required for any non-dry-run execution (audited narrow manual override; same pattern as --allow-active-wireless and --allow-dynamic-mobile).
  • Dry-run (--dry-run) is always safe: it produces a complete, valid DbPentestReport with synthetic findings, exercises 100% of report generation / policy paths / manifest logic, and performs zero network or database interaction.
  • Never run against production or customer databases without explicit written authorization and isolation. Prefer dedicated lab instances with no production data.
  • Production impact: none for dry-run; real runs execute read-only queries (bounded) and can be noticed by monitoring/auditing on the target DB.
  • The CLI surfaces prominent warnings about authorized lab use unless --quiet.

Phase Status

  • Phase 1 (2026-06-12): Foundations + Postgres + MySQL + manifest + policy (DbPentest risk + --allow-db-pentest) + full dry-run contract + to_scan_report_data_db bridge + auto-wire in report convert + CLI + tests + docs + AGENTS + smoke script. All delivered; committed to main.
  • Phase 2 (2026-06-12, delivered on main): Real MSSQL support via tiberius (gated behind explicit marker feature db-pentest-mssql-tiberius + tiberius dep in Cargo.toml so plain --features db-pentest never pulls the driver). Full dry-run parity for mssql (db-mssql-* categories). qcount warnings eliminated; report.queries_executed used for budget checks. Docker lab services added under new db-lab profile (postgres-lab:5433, mysql-lab:3307 with local_infile, mssql-lab:1434 with xp_cmdshell enablement). Smoke script --real leg fully implemented (compose up + deliberate misconfigs + real runs against all three + validation). All compile/test/clippy/smoke (dry) green under --features db-pentest,db-pentest-mssql-tiberius. No TUI/pipeline/MCP; standalone defense-lab surface preserved. (completed).
  • Phase 3 (2026-06-12, delivered on main): TUI tab (Tab::DbPentest = 30, direct_launch, Intrusive risk for advanced, TaskConfig/TaskResult wiring, workers/db_pentest.rs). Pipeline ScanProfile::DbRegression recognized (maps to defense-lab stages; eggsec scan --profile db-regression works). Advanced gated checks: --allow-db-pentest-advanced narrow audited flag, dry-run always exercises 100% of advanced simulation paths with "would..." actions + cleanup notes, real requires full policy + manifest + confirmation. Correlation stub (correlate_db_with_sqli) + evidence bundle export (export_db_evidence_bundle, flate2 gzipped). (completed).
  • Phase 4 (2026-06-12, delivered on main): Full real advanced reversible test vectors with automatic cleanup (AdvancedTestVector enum: TempUdfCreateDrop, LinkedServerProbe, FileAccessViaExtension). Real execution requires --allow-db-pentest-advanced + manifest + policy confirmation. Correlation engine (DbCorrelationEngine with 14 rules, scoring 0-100, DbCorrelationType classification Direct/Indirect/Behavioral/CrossLayer, enrichment, timeline). Native Stage::DbPentest pipeline stage (cfg-gated behind db-pentest; ScanProfile::DbRegression uses it when enabled, falls back to generic stages otherwise). Evidence bundle v2 includes correlation data, version bumped to 2. --evidence-bundle CLI flag to export gzipped bundle. Human/JSON output includes correlation summary. Bridge includes correlation in info finding description. (completed).
  • Phase 5 (2026-06-12): Additional database engines — MongoDB (db-mongodb-* checks, behind db-pentest-mongodb marker) and Redis (db-redis-* checks, behind db-pentest-redis marker). Compliance mapping integration (OWASP, PCI DSS, HIPAA, SOC2 findings in reports). MCP opt-in via db-pentest-mcp marker (SecurityTool implementation in tool/implementations/db_pentest.rs with EnforcementContext enforcement). Connection string auto-detection for mongodb:// and redis:// URIs. All Phase 1–4 safety model, dry-run contract, manifest, budgets, and bridge patterns preserved.

See also: docs/SAFETY.md, architecture/defense_lab.md, AGENTS.md (Standalone Defense-Lab Surfaces section), and the central EnforcementContext policy gate (handler uses DbPentest risk for real runs / SafeActive for dry-run + required "db-pentest" feature).

CLI Usage

# Basic dry-run (always safe; produces complete DbPentestReport; no DB/network)
eggsec db pentest postgres://labuser@127.0.0.1:5432/labdb --dry-run --json

# Dry-run with explicit components (no conn string)
eggsec db pentest --type mysql --host 127.0.0.1 --port 3306 --user root --dry-run --json

# Real run (requires --allow-db-pentest + policy approval or --manual-override-reason)
eggsec db pentest postgres://labuser:labpass@127.0.0.1:5432/labdb \
  --checks all \
  --max-queries 200 \
  --max-duration 120 \
  --lab-manifest examples/lab-db-manifest.toml \
  --allow-db-pentest \
  --manual-override-reason "Authorized lab Postgres hardening regression" \
  --json -o db-report.json

# MySQL real example (selective checks)
eggsec db pentest --type mysql --host lab-mysql.internal --port 3306 --user app --password secret \
  --checks misconfig,privs,version \
  --lab-manifest examples/lab-db-manifest.toml \
  --allow-db-pentest \
  --json

# MongoDB dry-run (requires --features db-pentest-mongodb)
eggsec db pentest --type mongodb --host 127.0.0.1 --port 27017 --user admin --dry-run --json

# MongoDB with connection string
eggsec db pentest mongodb://admin:pass@127.0.0.1:27017/labdb --dry-run --json

# Redis dry-run (requires --features db-pentest-redis)
eggsec db pentest --type redis --host 127.0.0.1 --port 6379 --dry-run --json

# Redis with connection string
eggsec db pentest redis://127.0.0.1:6379 --dry-run --json

# With global flags and quiet
eggsec --json db pentest postgres://... --dry-run -o plan.json --quiet

# Help
eggsec db pentest --help
eggsec db --help

# Dry-run with advanced test vector simulation (always safe; exercises reversible test vectors without connection)
eggsec db pentest postgres://labuser@127.0.0.1:5432/labdb --dry-run --json --allow-db-pentest-advanced

# Real advanced execution (requires --allow-db-pentest + --allow-db-pentest-advanced + manifest + policy confirmation)
eggsec db pentest postgres://labuser:labpass@127.0.0.1:5432/labdb \
  --checks misconfig,privs \
  --lab-manifest examples/lab-db-manifest.toml \
  --allow-db-pentest --allow-db-pentest-advanced \
  --manual-override-reason "Lab advanced vector validation" \
  --json -o db-advanced.json

# Evidence bundle export v2 (Phase 4: gzipped JSON with report + manifest + correlation + timeline)
eggsec db pentest postgres://labuser@127.0.0.1:5432/labdb --dry-run \
  --evidence-bundle db-dry-bundle.json.gz

# Real run with evidence bundle
eggsec db pentest postgres://labuser:labpass@127.0.0.1:5432/labdb \
  --lab-manifest examples/lab-db-manifest.toml \
  --allow-db-pentest --allow-db-pentest-advanced \
  --manual-override-reason "Lab hardening + bundle" \
  --evidence-bundle db-lab-bundle.json.gz \
  --json -o db-report.json

# Pipeline profile (Phase 4: uses native Stage::DbPentest when db-pentest feature enabled)
eggsec scan --target 127.0.0.1 --profile db-regression --dry-run

Important: The command prints a clear standalone defense-lab warning (unless --quiet). Use only in lab/defense-validation contexts. --dry-run is the recommended starting point for CI, planning, and flag validation.

Lab Manifest: Supply a TOML file via --lab-manifest. It is loaded and recorded in actions_performed. In permissive modes it produces warnings on mismatch; strict profiles may deny. See example below and examples/lab-db-manifest.toml.

Budgets & Redaction: --max-queries (default 200) and --max-duration (default 120s) are respected in both dry-run (simulated) and real paths. Credentials are never emitted in human/JSON output or bridged evidence.

What It Detects (Phase 1/2/4 High-Signal Checks)

Findings are severity-rated (Critical/High/Medium/Low/Info) with title, description, recommendation, category, and optional redacted evidence. Categories are prefixed db-postgres-*, db-mysql-*, db-mssql-*, db-mongodb-*, or db-redis-*.

Postgres (primary):

  • Connection success + version string (Info)
  • Connected as superuser role (High)
  • Additional superuser roles discovered (Medium)
  • Dangerous extensions installed and potentially grantable (pg_read_server_files, pg_write_server_files, pg_execute_server_program, dblink, postgres_fdw) (High)
  • Public schema ownership/permissions issues (Medium)
  • log_statement set to none (Low)
  • Bounded enumeration findings (many tables/schemas sampled) (Info)
  • Basic version-to-CVE note (Low; placeholder mapping — cross-reference NVD in practice)

MySQL (secondary):

  • Connection success + version string (Info)
  • local_infile enabled (Medium)
  • secure_file_priv empty or NULL (High)
  • Excessive global privileges (FILE, SUPER, ALL PRIVILEGES) (Medium)
  • Binary logging not enabled (Low)
  • Bounded schema enumeration (Info)

Advanced Test Vectors (Phase 4, --allow-db-pentest-advanced + real run):

  • db-{type}-advanced-temp-udf (Low): Temp UDF create/invoke/drop confirms CREATE FUNCTION privilege. Automatic cleanup on success or failure.
  • db-postgres-advanced-file-access-probe (Info/Low): Probes pg_read_server_files/pg_write_server_files/file_fdw extensions and CONNECT privilege. Read-only, no file I/O.
  • db-mssql-advanced-linked-server-probe (Medium/Low): Enumerates linked servers via sys.servers WHERE is_linked = 1. Read-only probe.

MongoDB (Phase 5, --type mongodb, requires db-pentest-mongodb marker feature):

  • Connection success + server version (Info)
  • Authentication disabled / no auth (High)
  • Binding to all interfaces (0.0.0.0) (Medium)
  • Excessive user roles or root access from non-localhost (Medium)
  • test database left in production (Low)
  • Bounded collection enumeration (Info)

Redis (Phase 5, --type redis, requires db-pentest-redis marker feature):

  • Connection success + Redis version (Info)
  • No password configured (requirepass not set) (High)
  • Binding to all interfaces (Medium)
  • protected-mode disabled with no auth (High)
  • Dangerous commands enabled (FLUSHALL, KEYS, CONFIG SET) (Medium)
  • Bounded key pattern enumeration (Info)

Compliance Mapping (Phase 5): Findings are automatically mapped to compliance frameworks when applicable (map_findings_to_compliance() in crates/eggsec-db-lab/src/compliance.rs:196). Compliance tags appear in finding metadata (e.g. OWASP A05, PCI-DSS 6.5.1, HIPAA §164.312, SOC2 CC6.1). There is no --compliance CLI filter — the mapping is applied automatically and summarized in the report; filter downstream in your own tooling if you need a single framework.

Correlation (Phase 4): When correlation field is populated (both dry-run and real), findings are cross-referenced with web SQLi signals:

  • Direct (85-90 score): Excessive privs/extensions + SQLi = privilege escalation / server-side execution risk
  • CrossLayer (70 score): Linked server + SQLi = lateral movement risk
  • Indirect (20-65 score): Weak logging, version, public schema + SQLi = amplification

General recommendations are appended for file/system access vectors, least-privilege, logging/auditing, and patching. All checks use safe catalog/information_schema views or bounded LIMIT queries.

Findings and metadata are also exposed via to_scan_report_data_db() for unified reporting. The bridged info finding includes correlation summary when present.

Output & Integration

  • Human-readable text (default) includes target (redacted), DB type, dry-run/manifest status, duration/queries vs budget, Actions audit trail, per-finding blocks (severity/title/category/description/recommendation/evidence), compliance tags (when applicable), Recommendations section, and a prominent lab-use note.
  • --json produces the full DbPentestReport (target, db_type, scan_type: "db-pentest", findings array, recommendations, duration_ms, queries_executed, actions_performed, manifest_matched, dry_run, budgets, lab_manifest_path). This native shape is accepted directly by eggsec report convert (auto-bridged to ScanReportData when the db-pentest feature is enabled).
  • -o / --output supported for both modes (writes to file; still prints path to stderr unless quiet).
  • Structured findings feed into ScanReportData (via to_scan_report_data_db()) for SARIF, JUnit, HTML, Markdown, CSV, JSON roundtrip, trend, etc. pipelines. The bridge is optional and opt-in: use it (or rely on the CLI auto-bridge for report convert) when you need unified report consumers; otherwise consume the native DbPentestReport directly for lab-specific workflows.
  • Phase 2 explicit deliverable: Combined web-SQLi + db-pentest unified reports are supported via manual combination (or pipeline consumers) followed by report convert. The smoke produces (and validates) a stable checked-in artifact at examples/combined-db-web-example.json containing both db-* (e.g. db-postgres-*) and sqli-* categories side-by-side in one ScanReportData-shaped report. This demonstrates immediate value of the optional bridge for mixed web+db lab sessions without requiring engine changes. Convert the combined artifact the same way:
eggsec report convert examples/combined-db-web-example.json -f sarif -o combined.sarif
eggsec report convert examples/combined-db-web-example.json -f html  -o combined.html

Compatible with the existing report tooling (single-db examples remain valid):

eggsec db pentest postgres://... --dry-run --json -o db.json
eggsec report convert db.json -f sarif -o db.sarif
eggsec report convert db.json -f html -o db.html
eggsec report convert db.json -f markdown -o db.md
eggsec report convert db.json -f junit -o db.xml

See docs/USAGE.md (Report Management section) and docs/FINDINGS_SCHEMA.md for unified report consumers.

Integration with Reporting Pipeline

eggsec db pentest is intentionally a standalone defense-lab CLI (no MCP/agent SecurityTool registration by default). It emits local DbPentestReport / DbFinding types directly for human and --json use. An optional to_scan_report_data_db() bridge (re-exported by the engine facade crates/eggsec/src/db_pentest/mod.rs, implemented in crates/eggsec-db-lab/src/bridge.rs) converts to the canonical ScanReportData (owned by eggsec-report-model, re-exported by output) used by eggsec-output converters (SARIF, JUnit, HTML, Markdown, CSV, JSON roundtrip, trend, etc.).

  • Use the native types for lab-specific flows, regression on DbPentest* shapes, or when you do not need unified consumers.
  • Use --json + eggsec report convert (or call to_scan_report_data_db in your own tooling) when you want SARIF/JUnit/etc. or to feed into report trend / other unified consumers.
  • ScanProfile::DbRegression in Phase 4 uses the native Stage::DbPentest pipeline stage when the db-pentest feature is enabled. When the feature is absent, it falls back to the generic defense-lab stages (PortScan, Fingerprint, EndpointScan, Waf, Fuzz).
  • Phase 4: evidence bundle v2 (--evidence-bundle) exports a gzipped JSON aggregate with report + manifest + correlation + timeline. Useful for audit trails, regression tracking, and offline analysis.
  • Design decision (Phase 1-4): keep the surface standalone and lightweight; the bridge provides reporting unification without forcing the module into the main chained pipeline.

The auto-bridge in commands/handlers/report.rs makes the documented --json | report convert flow work out of the box when built with --features db-pentest. Categories in bridged output are of the form db-postgres-*, db-mysql-*, db-mssql-*, db-mongodb-*, or db-redis-* (e.g. db-postgres-misconfig-dangerous-extension, db-mysql-misconfig-local-infile, db-mongodb-misconfig-no-auth, db-redis-misconfig-no-password, plus a db-*-info metadata finding carrying budgets/actions/dry_run/manifest status). Evidence in bridged findings carries through useful redacted details (extension name, role, setting value, sampled count). Empty findings produce a valid bridge with 0 high-signal findings + the info metadata finding (tested).

This is one of the consolidated "standalone defense-lab surfaces" (wireless + mobile + auth-test + db-pentest). Wireless and mobile provide local types directly + optional to_scan_report_data bridge (auto-bridged by eggsec report convert when the feature is present); auth-test is local-only (no bridge). db-pentest follows the wireless/mobile pattern (local types + optional bridge). Phase 3 added TUI tab + pipeline profile; none participate in ScanProfile native stage executors (aspirational only). See the short shared "Output Models" explanation in docs/USAGE.md (Report Management → Convert Reports), architecture/{wireless,mobile,auth,cli_commands,defense_lab,output}.md, AGENTS.md (standalone defense-lab surfaces note), and CAPABILITIES.md (Lab Defense table). MCP/agent tool exposure is intentionally absent for db-pentest (standalone defense-lab design decision; see architecture/defense_lab.md and the loadout plans).

Data Model (Key Types)

pub struct DbPentestReport {
    pub target: String,                 // redacted
    pub db_type: String,                // "postgres" | "mysql" | "mssql"
    pub scan_type: String,              // "db-pentest"
    pub timestamp: String,
    pub findings: Vec<DbFinding>,
    pub recommendations: Vec<String>,
    pub duration_ms: u64,
    pub queries_executed: u64,
    pub actions_performed: Vec<String>, // full audit trail ("would ..." in dry-run)
    pub manifest_matched: bool,
    pub dry_run: bool,
    pub max_queries_budget: u64,
    pub max_duration_budget_secs: u64,
    pub lab_manifest_path: Option<String>,
    pub correlation: Option<DbCorrelationResult>, // Phase 4: scoring + timeline
}

pub struct DbFinding {
    pub category: String,           // e.g. "db-postgres-misconfig-dangerous-extension"
    pub severity: Severity,
    pub title: String,
    pub description: String,
    pub recommendation: String,
    pub evidence: Option<String>,   // redacted
    pub db_type: String,
    pub target_host: String,
}

pub struct DbCorrelationResult {        // Phase 4
    pub correlations: Vec<DbCorrelatedFinding>,
    pub timeline: Vec<String>,
    pub summary: DbCorrelationSummary,
}

pub struct DbCorrelatedFinding {        // Phase 4
    pub db_finding_category: String,
    pub web_finding_category: String,
    pub note: String,
    pub score: Option<u8>,           // 0-100
    pub correlation_type: Option<DbCorrelationType>, // Direct/Indirect/Behavioral/CrossLayer
    pub enrichment: Option<String>,
}

pub struct LabDbManifest {
    pub description: Option<String>,
    pub allowed_hosts: Vec<String>,
    pub allowed_ports: Vec<u16>,
    pub allowed_databases: Vec<String>,
    pub max_queries_default: Option<u64>,
    pub max_duration_secs_default: Option<u64>,
}

pub fn to_scan_report_data_db(result: &DbPentestReport) -> ScanReportData { ... }

See crates/eggsec-db-lab/src/{mod,types,manifest,postgres,mysql,bridge,correlation,advanced}.rs for full definitions, run_db_pentest_cli, export_db_evidence_bundle, DbCorrelationEngine, and the bridge. The utils module contains shared URL builders, connection string parsing, redaction helpers, and dry-run population.

Example lab manifest (examples/lab-db-manifest.toml):

description = "Authorized lab Postgres, MySQL, and MSSQL instances for defense regression and hardening validation"
allowed_hosts = ["127.0.0.1", "localhost", "lab-pg.internal", "lab-mysql.internal", "lab-mssql.internal"]
allowed_ports = [5432, 3306, 1433]
allowed_databases = ["lab", "test", "defense", "regression"]
max_queries_default = 200
max_duration_secs_default = 120

Phase 2 combined web+db example artifact (checked in for consumers and CI demos): examples/combined-db-web-example.json — a ScanReportData-shaped report with both db-postgres-* (and db-*-info) and sqli-error-based categories side-by-side, produced via manual combination of bridged outputs and validated in smoke. Use it directly with report convert or as a template for your own mixed-lab sessions.

Example Output (Human, abbreviated)

[db-pentest] Standalone defense-lab mode. Use only on lab instances you own and are authorized to test.
Dry-run is always safe and produces a complete report. Real runs are policy-gated.
=== Database Pentest Report (defense-lab) ===
Target: postgres://labuser@127.0.0.1:5432/labdb
DB Type: postgres  |  Dry-Run: true  |  Manifest matched: true
Duration: 12ms  |  Queries: 42/200
Actions:
  - loaded lab manifest: examples/lab-db-manifest.toml
  - dry-run: no database connection attempted
  - ...

Findings:
  [High] Dangerous extension 'pg_read_server_files' installed (owner: postgres) (db-postgres-misconfig-dangerous-extension)
    This extension can provide file system or remote execution access.
    Recommendation: Drop the extension if not required; otherwise ensure it is not grantable to non-superuser roles.
    Evidence: extension=pg_read_server_files owner=postgres

  ...

Recommendations:
  - Review and revoke unnecessary file/system access privileges and extensions.
  - ...

NOTE: This is a lab-only defensive validation tool. Use only on systems you own and are authorized to test.

(Full structured JSON available via --json; bridged reports include db-postgres-* / db-mysql-* + info metadata finding.)

Recommended Workflows

  • Lab / defense validation & regression: Start with --dry-run --json to validate command shape and produce a baseline. Supply --lab-manifest. Run real (with --allow-db-pentest) against a dedicated lab instance with known misconfigs; capture JSON; harden the DB; re-run and diff (eggsec report diff or your tooling).
  • CI / regression: --dry-run --json (or real against isolated lab DBs with manifests) + to_scan_report_data_db (or rely on CLI auto-bridge) into SARIF/JUnit for "no dangerous extensions / excessive privs / weak logging" gates.
  • Combined reporting (Phase 2+): Use the explicit combined example workflow: run db-pentest (dry or real) + a web fuzzer against the same lab session; manually combine the bridged outputs (or let a consumer do so) into one ScanReportData-shaped JSON with db-* + sqli-* findings; feed through eggsec report convert (or your pipeline). A stable artifact + smoke validation lives at examples/combined-db-web-example.json. The bridge carries evidence and remediation through for both families.
  • Manifest-driven: Create per-lab or per-team manifests; commit them alongside scope files. Use in both dry-run (for planning) and real runs.
  • Advanced test vectors (Phase 3): Use --dry-run --allow-db-pentest-advanced to exercise the full advanced simulation (reversible test vectors, cleanup notes) with zero risk. Real advanced execution requires --allow-db-pentest-advanced + --allow-db-pentest + manifest + policy confirmation.
  • Budget tuning: Start with defaults; increase --max-queries only when you need deeper (still bounded) enumeration on large lab schemas.

Best Practices (Lab / Defensive Use)

  • Always start with --dry-run --json: Validates flags, manifest loading, policy paths, and report shape with zero risk.
  • Use --lab-manifest: Even when advisory, it documents intent and produces audit entries. Strict profiles benefit from it.
  • Provide --allow-db-pentest --manual-override-reason for real runs (audited). The reason appears in policy decision records.
  • Least-privilege lab accounts: Connect with the exact role an application would use; avoid superuser/root for routine testing.
  • Redaction & evidence: Evidence is intentionally redacted (no passwords, no row data values). Column names, extension names, role names, and setting values are safe for reports.
  • JSON for automation: --json produces machine-readable DbPentestReport. Pipe to eggsec report or your own post-processing / trend tooling.
  • Baseline before/after: Capture a JSON baseline on a "known hardened" lab state; re-test after config changes or upgrades and highlight regressions via findings or report diff.
  • Interpret conservatively: Many "Medium/High" items (e.g. dangerous extensions, FILE priv) may be intentional in isolated lab setups. Always review in the context of your threat model and data classification.
  • Cleanup: Phase 1 performs no state changes. Later phases with reversible test actions will document best-effort cleanup.
  • Prefer lab environments: db-pentest is a defense-lab / regression tool. Do not use for unauthorized production assessment. Know your local regulations and organizational policies.

Example practical flows:

# Single authoritative dry-run + JSON record (CI-safe)
eggsec db pentest postgres://labuser@127.0.0.1:5432/labdb --dry-run --json -o baseline.json

  # Lab regression with manifest (real; requires allow)
  eggsec db pentest postgres://labuser:labpass@127.0.0.1:5432/labdb \
    --checks all --lab-manifest examples/lab-db-manifest.toml \
    --allow-db-pentest --manual-override-reason "Postgres hardening regression - lab only" \
    --json -o after-hardening.json

  # MySQL quick validation
  eggsec db pentest --type mysql --host 127.0.0.1 --port 3306 --user root --dry-run --json

  # Combined web-SQLi + db-pentest (Phase 2 pattern): produce a mixed report then convert
  # (example artifact with db-* + sqli-* side-by-side is checked in)
  eggsec report convert examples/combined-db-web-example.json -f sarif -o combined.sarif

Not In Scope (This Phase)

  • Oracle DB support (deferred; future phase)
  • TUI tab for advanced action queue (Phase 3 delivered TUI tab; advanced action queue in pipeline deferred)
  • Unbounded enumeration, data exfiltration, or destructive operations
  • Cloud-managed DB specifics as primary focus (RDS, Cloud SQL, etc. — note shared-responsibility differences; prefer self-hosted lab equivalents for full testing)
  • iOS/Android/embedded DB focus (server-focused)

In Scope (Phase 5)

  • MongoDB: db-mongodb-* checks (auth, binding, roles, enumeration) behind db-pentest-mongodb marker feature
  • Redis: db-redis-* checks (auth, protected-mode, dangerous commands, enumeration) behind db-pentest-redis marker feature
  • Compliance mapping: OWASP, PCI DSS, HIPAA, SOC2 tags attached to findings automatically by map_findings_to_compliance(); no --compliance flag exists on eggsec db pentest
  • MCP opt-in: db-pentest-mcp marker feature enables SecurityTool registration in tool/implementations/db_pentest.rs with EnforcementContext enforcement (standalone defense-lab model preserved)

Troubleshooting

  • "db-pentest feature not enabled": Rebuild with --features db-pentest (or --features full).
  • "Direct database pentest requires --allow-db-pentest": Real (non-dry-run) paths are intentionally gated. Use --dry-run for planning/safe validation, or pass --allow-db-pentest --manual-override-reason "..." for authorized lab runs. The flag is audited on the policy decision.
  • "manifest did not match target (advisory...)": Normal in permissive mode when --lab-manifest is supplied but the target falls outside the allowlist. Update the manifest or use a matching lab target. Strict profiles may deny.
  • Connection / auth errors on real runs: Verify host/port reachability from the eggsec host, credentials, and that the lab DB is listening/accepting connections. Use --dry-run to validate everything else.
  • No (or few) findings: The checks are intentionally high-signal only (dangerous extensions, excessive privs, weak logging, etc.). Provide a lab DB with deliberately introduced misconfigurations for testing. Use --checks all (default).
  • Budget exceeded / truncated results: The tool respects --max-queries / --max-duration. Increase via CLI or manifest defaults for deeper (still bounded) sampling on large lab schemas.
  • Policy confirmation or strict profile denial: Under ManualPermissive (default CLI) you may see a confirmation prompt for RequireConfirmation (DbPentest / DefenseLab). Strict/MCP/agent profiles treat real db-pentest as Deny (standalone defense-lab surface; no MCP/agent exposure by design). Use --yes or the specific --allow-db-pentest flag as appropriate.
  • Report bridge / convert issues: Native --json DbPentestReport is auto-bridged by eggsec report convert when the feature is present (categories become db-postgres-* / db-mysql-* + info metadata). If mixing with other report types the bridge preserves categories.
  • "Unsupported db type in Phase 1": Only postgres, mysql, and mssql (inferred from conn string or --type) are supported. Use one of those targets. (MSSQL real driver requires the marker feature + tiberius dep to resolve.)
  • "Advanced simulation only available in dry-run": The --allow-db-pentest-advanced flag enables advanced simulation in dry-run (always safe). Real advanced execution requires the flag plus --allow-db-pentest, manifest match, and policy confirmation.
  • For combined web+db flows: the smoke produces examples/combined-db-web-example.json (db-* + sqli-*). If your manual combination yields an unexpected shape, fall back to converting the individual bridged JSONs and let your consumer merge the findings arrays.

See crates/eggsec-db-lab/src/{mod,postgres,mysql,mongodb,redis}.rs (real driver paths), commands/handlers/db_pentest.rs (policy + allow gate), cli/db_pentest.rs (ABOUT + flags), and the architecture docs for the safety model.

MCP Opt-In (Phase 5)

By default, db-pentest is a standalone defense-lab CLI with no MCP/agent exposure. Build with --features db-pentest-mcp to enable SecurityTool registration so the db-pentest commands are available through the MCP server for AI agent workflows. The implementation lives in tool/implementations/db_pentest.rs and enforces EnforcementContext policy checks before dispatching any operation.

cargo build --release -p eggsec-cli --features db-pentest,db-pentest-mcp

The MCP surface preserves the same safety model: --allow-db-pentest is still required for non-dry-run operations, and --lab-manifest / budget limits apply. EnforcementContext::evaluate() is the mandatory pre-dispatch gate for all MCP tool calls. The db-pentest-mcp marker is separate from the base db-pentest feature so that the MCP surface is opt-in and subject to security review.

Policy Note

  • Gated via CommandContext::evaluate_and_enforce_operation() (commands/handlers/db_pentest.rs).
  • operation: "db-pentest", mode: DefenseLab, risk: OperationRisk::DbPentest (real) or SafeActive (dry-run), required_features: ["db-pentest"].
  • Non-dry-run requires explicit --allow-db-pentest (audited; narrow manual override; same pattern as wireless deauth / mobile dynamic).
  • Additional runtime confirmation prompt under ManualPermissive for operator discretion (high-risk real runs).
  • Lab manifest (if provided) is loaded and recorded; enforcement is primarily policy + provenance + manifest match + user responsibility.
  • MCP/agent SecurityTool registration: optional via db-pentest-mcp marker feature (defense-lab only, no new runtime deps). Implementation in tool/implementations/db_pentest.rs with EnforcementContext enforcement.
  • Always produces policy decision + actions audit even in dry-run.
  • Dry-run bypasses network/DB but still exercises full policy + manifest + report generation.

See config/policy_decision.rs, commands/handlers/db_pentest.rs, crates/eggsec-db-lab/src/, and the architecture docs for descriptors and ConfirmationClass handling.

Future

  • Phase 1 (this document): Postgres primary + MySQL secondary foundation; full safety model, dry-run contract, CLI, manifest, budgets, policy, reporting bridge. Standalone defense-lab only.
  • Phase 2 (complete 2026-06-12): Microsoft SQL Server (tiberius/sqlx), docker lab services, --real smoke, combined web-SQLi+db example artifact, qcount cleanup, cross-DB dry-run parity. See executed plan.
  • Phase 3 (complete 2026-06-12): TUI tab (Tab::DbPentest), pipeline ScanProfile::DbRegression, advanced gated checks (--allow-db-pentest-advanced), correlation stub (correlate_db_with_sqli), evidence bundle export (export_db_evidence_bundle). See executed plan.
  • Phase 4 (complete 2026-06-12): Full real advanced execution (reversible test vectors with auto-cleanup), scoring/enrichment correlation engine (DbCorrelationEngine, 14 rules, scoring, timeline), native Stage::DbPentest pipeline stage, evidence bundle v2 with correlation, --evidence-bundle CLI flag. See executed plan.
  • Phase 5 (complete 2026-06-12): MongoDB + Redis engines (marker features), compliance mapping (OWASP/PCI/HIPAA/SOC2 in findings), MCP opt-in (db-pentest-mcp marker with SecurityTool implementation in tool/implementations/db_pentest.rs), connection string auto-detection for mongodb:// and redis://. All Phase 1–4 safety/contract patterns preserved.
  • Phase 6 (complete 2026-06-14): Baseline capture + regression comparison (DbBaseline/DbRegressionResult/SeverityChange), MCP deepening (baseline operations, parameterized calls), extended compliance (NIST SP 800-53, ISO 27001), cloud DB guidance notes. Cleanup + polish: shared URL builders in utils.rs, standardized error handling, improved redaction, types-only MCP module.
  • Phase 7+: Oracle DB support, additional compliance frameworks, advanced correlation patterns.

See architecture/defense_lab.md and architecture/database_pentest.md.

References

  • Source: crates/eggsec-db-lab/src/{mod,types,manifest,postgres,mysql,mongodb,redis,bridge,correlation,advanced,compliance,utils}.rs (domain crate; engine facade crates/eggsec/src/db_pentest/mod.rs re-exports it)
  • CLI: crates/eggsec/src/cli/db_pentest.rs
  • Handler/policy: crates/eggsec/src/commands/handlers/db_pentest.rs
  • MCP SecurityTool: crates/eggsec/src/tool/implementations/db_pentest.rs
  • Report auto-bridge: crates/eggsec/src/commands/handlers/report.rs
  • Report data contracts: crates/eggsec-report-model/src/
  • Output conversion: crates/eggsec-output/src/convert.rs
  • Pipeline stage: crates/eggsec/src/pipeline/{stage,executor}.rs
  • Examples: examples/lab-db-manifest.toml
  • Architecture: architecture/defense_lab.md, architecture/database_pentest.md
  • AGENTS.md (Standalone Defense-Lab Surfaces section and feature matrix)
  • Safety: docs/SAFETY.md

Phase 1 complete 2026-06-12. Phase 2 (real MSSQL tiberius + docker lab services + smoke --real + combined web-SQLi+db example artifact + polish) complete 2026-06-12; merged to main. Phase 3 (TUI tab + ScanProfile::DbRegression + advanced gated checks + correlation/evidence stubs) complete 2026-06-12; merged to main. Phase 4 (real advanced checks + correlation engine + native pipeline stage + evidence bundles) complete 2026-06-12; merged to main. Phase 5 (MongoDB + Redis engines + compliance mapping + MCP opt-in) complete 2026-06-12; merged to main.