Defense-lab framing: eggsec auth-test exists for controlled validation of authentication defenses (lockout policies, rate limiting, MFA enforcement, session handling, timing side-channels, brute-force resistance) in authorized lab or private environments only. It is not a credential attack or exploitation tool.
allow_credential_testing = trueunder[execution_policy]in your config (default:false).- Explicit scope manifest (
--scopeor config) that covers both the target endpoint and any test accounts/usernames used. - Dedicated test accounts only. Never use production or real-user credentials.
- Rate/attempt caps: use
--max-attempts,--concurrency,--timeout, and scope-levelmax_requests_per_second. Start very low (e.g. 50 attempts total).
High-risk operations are blocked by default. ManualPermissive (default CLI/TUI) surfaces RequireConfirmation for CredentialTesting; strict profiles (MCP, agent, CI, --strict-scope) treat it as hard Deny. Use --yes (narrow) or --allow-high-risk (audited) only when you have explicit authorization.
eggsec auth-test https://lab-target.example.com/login \
--all \
--wordlist /path/to/lab-test-credentials.txt \
--max-attempts 50 \
--concurrency 2 \
--yesOr with explicit high-risk allowance:
eggsec auth-test ... --all --wordlist ... --max-attempts 50 --allow-high-risk --manual-override-reason "authorized lab control validation"# eggsec.toml — enables the credential-testing risk tier (does not authorize
# a specific run; each run still needs --allow-high-risk or an operator
# confirmation)
[execution_policy]
allow_credential_testing = true
# allow_intrusive_fuzzing = false
# ... other gates ...# scope.toml — passed via --scope; must authorize the lab target and test
# accounts. See examples/configs/scope.toml for the full commented template.
require_explicit_scope = true
max_requests_per_second = 10
[[allowed_targets]]
pattern = "lab-target.example.com"
description = "Auth control validation lab target"See examples/configs/eggsec.toml and examples/configs/scope.toml for the commented templates.
- Account lockout: Even small attempt counts can lock legitimate test accounts. Coordinate with the team that manages auth for the target.
- Legal / authorization: You must have explicit written authorization that covers credential control validation. Document scope, accounts used, attempt budgets, and time window.
- Never production credentials: Only synthetic or dedicated lab accounts. Breach lists or real-user data are out of scope and prohibited.
- Monitor and rollback: Watch target logs, auth service health, and have a kill-switch. Expect to reset test accounts after runs.
- Multi-protocol testers (SSH/FTP/SMTP) additionally require the
nse-ssh2feature.
eggsec auth-test is deliberately designed as a standalone defense-lab CLI command. It produces and emits only local AuthTestReport / AuthFinding types (defined in the auth/ module). These are output directly as human-readable text or structured --json from the command handler.
It does not:
- Convert results to
ScanReportData,StoredFinding, or any canonical finding types from theeggsec-outputcrate. - Provide a
to_scan_report_data()bridge,FindingDatamapping, or similar conversion helper. - Participate in pipeline profiles, or produce SARIF, JUnit, CSV, HTML, etc. reports via the standard unified output system.
Why local findings only (by design):
auth-testis a high-risk operation (OperationRisk::CredentialTesting) intended exclusively for controlled validation of authentication defenses (brute-force resistance, account lockout policies, MFA enforcement, rate limiting effectiveness, timing side-channels, session handling) using dedicated lab test accounts only.- It operates completely outside the main assessment pipeline. Its results are specialized (per-test-type observations, attempt counts, observed behaviors like lockout thresholds, MFA step-up responses, etc.) and are not intended for unification into general vulnerability reports.
- The safety model (runtime policy gating via
allow_credential_testing, explicit scope manifest covering both target endpoint and test accounts, high-riskRequireConfirmationfor ManualPermissive, hard Deny for strict/automated profiles) is enforced at the handler boundary using the centralEnforcementContext. Canonical finding conversion was intentionally not implemented to preserve the narrow "lab-only control validation" framing and reduce risk of misuse or scope creep. - This is the adopted model (post-2026-06-10 policy alignment): standalone CLI surface, local-only types, direct emit. No conversion path exists or is planned.
How its output differs from normal pipeline scans:
Normal pipeline scans (eggsec scan <target> --profile <profile>) execute one or more chained stages from the assessment pipeline and always produce a full ScanReportData structure. This contains unified findings (with canonical severity, category, evidence, remediation, etc.) that flow through the eggsec-output crate for consistent, loadable, diffable, and exportable reports (JSON, SARIF, JUnit, HTML, CSV, Markdown, etc.).
ScanProfile::Auth (the profile named "auth") is itself a pipeline profile: it runs PortScan + Fingerprint + EndpointScan + Fuzz, focused on application-level authentication/authorization issues detectable via fuzzing payloads (JWT algorithm confusion, weak secrets, null signatures; OAuth/OIDC redirect_uri / state / grant-type flaws; IDOR via object enumeration, etc.). It does not invoke any of the credential testers (BruteForce, LockoutDetector, MfaTester, etc.) from the auth/ module.
When to use auth-test vs. ScanProfile::Auth:
-
Use
eggsec auth-test <target> ...(with--allor specific selectors like--brute-force/--lockout-detection/--mfa-bypass, a--wordlistor--credential-fileof synthetic lab credentials only, conservative--max-attempts/--concurrency/--timeout, and the required policy allowances such asallow_credential_testing = true+--allow-high-riskor equivalent) when your goal is to validate the effectiveness of authentication controls themselves in an explicitly authorized lab environment.Examples: "Does the account lockout policy actually trigger and stay enforced after N consecutive failures?", "Is step-up MFA reliably enforced on risky login patterns?", "Are rate limits + timing protections sufficient to make brute-force impractical?", "Do session tokens behave correctly after failed attempts?"
This requires an explicit scope that authorizes both the login endpoint and the test accounts being used, plus the high-risk policy gate.
-
Use
eggsec scan <target> --profile auth(or a custom profile that includes the "auth" stage) when performing a broader web or API security assessment that needs to probe for flaws in how authentication and authorization mechanisms are implemented in the application (e.g., JWT mis-issuance or weak verification, OAuth implementation errors, IDOR, session management issues detectable without direct credential testing).This flows through the standard pipeline, produces canonical
ScanReportData, and can be exported/loaded like any other scan profile.
See also the short "Distinct from..." bullet in Implementation Notes below.
- There is no dedicated Cargo feature named
credential-testing. Auth testing is always compiled; control is exclusively via runtime policy (allow_credential_testing+CredentialTestingrisk tier in the centralEnforcementContext). - Multi-protocol support lives under the
nse-ssh2feature (libssh2-backed). - Distinct from the pipeline
authprofile (ScanProfile::Auth), which performs PortScan + Fingerprint + EndpointScan + Fuzz focused on JWT/OAuth/IDOR issues (seearchitecture/pipeline.mdandarchitecture/auth.md). The CLIauth-testcommand invokes theauth/module testers directly and does not use the pipeline.
The TUI AuthTab (Tab::Auth) is fully integrated with TabSpec (TabRiskGroup::Intrusive, direct_launch: true, operation: "auth-test", cli_command: "eggsec auth-test" — crates/eggsec-tui/src/tabs/spec.rs:651), the shared task system (run_auth_task() → TaskResult::Auth), policy enforcement via central EnforcementContext, session save/restore, and copy-CLI equivalent. Local findings only — no ScanReportData bridge.
docs/AUTH_CONTEXT.md— multi-role auth-context files (--auth-context/--auth-role)docs/SAFETY.md— risk tiers, execution profiles,EnforcementContextdocs/SAFETY.md— "Authentication Testing" section with lab requirementsarchitecture/auth.md— module types, CLI surface, policy integration, TUI status, local-findings-only decisioncrates/eggsec/src/commands/handlers/auth_test.rs— handler,evaluate_and_enforce_operation,AUTH_BANNER, wordlist loading, reportingcrates/eggsec/src/config/policy.rs—OperationRisk::CredentialTesting,allow_credential_testingdocs/CAPABILITIES.md,README.md,AGENTS.md(key types + security notes + standalone defense-lab surfaces)