feat(cli): --registry-password-stdin and --zap-auth-password-stdin (#145)

Closes hardening item #2 from "Secret Handling & Credential Surface
Hardening" in docs/developer/SDK-ROADMAP.md. Two new flags on
`argus scan` let users supply credentials via stdin, mirroring
`docker login --password-stdin`. The value never appears on argv,
in shell history, in argus.yml, or in any persisted argus artifact
(argus-audit.json, argus.log, argus-results.*).

Implementation:

- argus/core/secrets.py: module-level `_STDIN_OVERRIDES` slot
  registry with set_stdin_override / get_stdin_override /
  clear_stdin_overrides. Slots are stable cross-scanner names
  ("registry_password", "zap_auth_password") so the same stdin
  value can fill the same logical credential across scanners
  (e.g., registry password for container + zap), while distinct
  credentials (registry vs. ZAP web-app auth) stay in separate
  slots.

- argus/cli.py:
    --registry-password-stdin → slot: registry_password
    --zap-auth-password-stdin → slot: zap_auth_password
  New helper _consume_stdin_password_flags(args) runs at the top
  of cmd_scan. Errors out cleanly when stdin is a TTY, when more
  than one stdin flag is set (stdin is single-stream), or when
  stdin is empty. Reads stdin once, strips a single trailing
  newline (multi-line tokens preserved for PEM-style payloads),
  routes the value into the slot registry.

- argus/scanners/container.py + zap.py: container_env / _build_env
  pass `stdin_override=get_stdin_override(slot)` to resolve_secret.
  Highest precedence: stdin > _env > literal > None.

Test coverage:
- 5 new tests in argus/tests/core/test_secrets.py::TestStdinOverrideSlots
  cover the slot APIs (set/get/clear/isolation/explicit-override-arg).
- 9 new tests in argus/tests/test_cli.py::TestStdinPasswordFlags cover
  the CLI helper: no-flag noop, single-flag happy path for both
  flags, trailing-newline trim, no-newline preserved, multi-line
  preserved, both-flags error, TTY error, empty-stdin error.

Docs + .ai/:
- docs/config-reference.md: new "Third form — CLI stdin" subsection
  in the credential-fields section with a precedence table and
  worked examples. The validation-rules list now sits below it.
- docs/cli-reference.md: regenerated from cli.py via
  scripts/ci/check_cli_docs.py --fix.
- .ai/architecture.yaml: core/secrets.py description updated in both
  SDK structure blocks to document the three-form precedence and the
  slot registry; explicit note that the stdin path never reaches the
  per-scanner config dict.
- docs/developer/SDK-ROADMAP.md: hardening item (2) flipped to
  shipped with implementation summary.

Full suite: 3080 passed, 2 skipped.

Co-authored-by: eFAILution <eFAILution@users.noreply.github.com>

Author: eFAILution

.ai/architecture.yaml

@@ -38,7 +38,7 @@ components:
       "core/exclusions.py": "Path exclusion set (builtins + .gitignore + config + CLI), ``**``-glob matcher"
       "core/tool_config.py": "Auto-discovery of per-scanner canonical config files (.bandit, .checkov.yaml, trivy.yaml, osv-scanner.toml, semgrep.yml)"
       "core/sbom.py": "SBOM format detection (CycloneDX JSON/XML, SPDX JSON/tag-value, Syft JSON) for ``argus scan --sbom``"
-      "core/secrets.py": "Credential resolution for any scanner config field. resolve_secret(config, field) accepts either <field> (literal, warned at config-load if vendor-shaped via looks_like_literal_secret) or <field>_env (env-var name reference; reads os.environ at scan time). validate_env_var_name enforces POSIX shell identifier rules. Stdlib-only. Used by scanners.container and scanners.zap; future scanners with credential needs use the same helper. See ADR-024."
+      "core/secrets.py": "Credential resolution for any scanner config field. resolve_secret(config, field, *, stdin_override=None) accepts three forms in precedence order: stdin_override (highest, populated by CLI --*-password-stdin flags via a module-level slot registry — set_stdin_override / get_stdin_override / clear_stdin_overrides), <field>_env (env-var name reference; reads os.environ at scan time), or <field> literal (back-compat, warned at config-load if vendor-shaped via looks_like_literal_secret). The stdin path never reaches the per-scanner config dict so it can't leak into argus-audit.json / argus.log. validate_env_var_name enforces POSIX shell identifier rules. Stdlib-only. Used by scanners.container and scanners.zap; future scanners with credential needs use the same helper. See ADR-024."
       "core/findings_view.py": "Shared UI-free logic for findings display — ViewState, SEVERITY_ORDER, finding_detail_rows, compute_summary, diff_scans (scan-over-scan bucketing keyed off (scanner, id, location)). Consumed by argus view terminal (TUI ``D`` keybind, DiffScreen) and argus view browser (web UI ``/diff`` route)."
       "viewers/": "`argus view` interfaces (optional extras)"
       "viewers/__init__.py": "ViewerUnavailable shared exception"
@@ -471,7 +471,7 @@ docsite:
       "core/exclusions.py": "Path exclusion set (builtins + .gitignore + config + CLI), ``**``-glob matcher"
       "core/tool_config.py": "Auto-discovery of per-scanner canonical config files (.bandit, .checkov.yaml, trivy.yaml, osv-scanner.toml, semgrep.yml)"
       "core/sbom.py": "SBOM format detection (CycloneDX JSON/XML, SPDX JSON/tag-value, Syft JSON) for ``argus scan --sbom``"
-      "core/secrets.py": "Credential resolution for any scanner config field. resolve_secret(config, field) accepts either <field> (literal, warned at config-load if vendor-shaped via looks_like_literal_secret) or <field>_env (env-var name reference; reads os.environ at scan time). validate_env_var_name enforces POSIX shell identifier rules. Stdlib-only. Used by scanners.container and scanners.zap; future scanners with credential needs use the same helper. See ADR-024."
+      "core/secrets.py": "Credential resolution for any scanner config field. resolve_secret(config, field, *, stdin_override=None) accepts three forms in precedence order: stdin_override (highest, populated by CLI --*-password-stdin flags via a module-level slot registry — set_stdin_override / get_stdin_override / clear_stdin_overrides), <field>_env (env-var name reference; reads os.environ at scan time), or <field> literal (back-compat, warned at config-load if vendor-shaped via looks_like_literal_secret). The stdin path never reaches the per-scanner config dict so it can't leak into argus-audit.json / argus.log. validate_env_var_name enforces POSIX shell identifier rules. Stdlib-only. Used by scanners.container and scanners.zap; future scanners with credential needs use the same helper. See ADR-024."
       "core/findings_view.py": "Shared UI-free logic for findings display — ViewState, SEVERITY_ORDER, finding_detail_rows, compute_summary, diff_scans (scan-over-scan bucketing keyed off (scanner, id, location)). Consumed by argus view terminal (TUI ``D`` keybind, DiffScreen) and argus view browser (web UI ``/diff`` route)."
       "viewers/": "`argus view` interfaces (optional extras)"
       "viewers/__init__.py": "ViewerUnavailable shared exception"

argus/cli.py

@@ -811,6 +811,30 @@ def _build_scan_parser(subparsers: argparse._SubParsersAction) -> None:
              "is available via 'reporting.keep_raw: false' in argus.yml.",
     )
 
+    # Credential stdin flags — read a password from stdin and use it
+    # as the highest-precedence credential for the named slot. Mirrors
+    # ``docker login --password-stdin``: keeps the value off the
+    # process argv (no ``ps``/``docker inspect`` exposure), off the
+    # shell history, and out of the config file. At most one stdin
+    # flag may be used per invocation (stdin is a single stream).
+    scan_parser.add_argument(
+        "--registry-password-stdin",
+        action="store_true",
+        dest="registry_password_stdin",
+        help="Read the private-registry password from stdin and use it "
+             "for any scanner that needs registry auth (container, zap "
+             "with app_image_ref). Overrides registry_password / "
+             "registry_password_env in argus.yml.",
+    )
+    scan_parser.add_argument(
+        "--zap-auth-password-stdin",
+        action="store_true",
+        dest="zap_auth_password_stdin",
+        help="Read the ZAP web-app authentication password from stdin. "
+             "Overrides scanners.zap.auth.password / password_env in "
+             "argus.yml.",
+    )
+
     # Container-specific flags (used with: argus scan container)
     container_group = scan_parser.add_argument_group(
         "container scanning",
@@ -1206,6 +1230,72 @@ def _build_report_parser(subparsers: argparse._SubParsersAction) -> None:
     )
 
 
+_STDIN_PASSWORD_FLAGS = {
+    # CLI flag attr name on argparse.Namespace -> credential slot
+    "registry_password_stdin": "registry_password",
+    "zap_auth_password_stdin": "zap_auth_password",
+}
+
+
+def _consume_stdin_password_flags(args: argparse.Namespace) -> int:
+    """Read a password from stdin for any ``--*-password-stdin`` flag.
+
+    Mirrors ``docker login --password-stdin``: the value is read once,
+    stored in ``argus.core.secrets`` under a named slot, and consumed
+    by scanner modules via ``get_stdin_override(slot)`` at scan time.
+    The value never reaches the per-scanner config dict, so it can't
+    leak into argus-audit.json / argus.log.
+
+    Returns ``EXIT_SUCCESS`` on success (including when no stdin flag was
+    provided) or ``EXIT_ERROR`` on a usage / TTY violation. Logs no
+    secret material.
+    """
+    active = [
+        slot for attr, slot in _STDIN_PASSWORD_FLAGS.items()
+        if getattr(args, attr, False)
+    ]
+    if not active:
+        return EXIT_SUCCESS
+
+    if len(active) > 1:
+        print(
+            f"Error: only one stdin password flag may be used per "
+            f"invocation (got: {', '.join(sorted(active))}). "
+            f"stdin is a single stream — pass other credentials via "
+            f"<field>_env config keys instead.",
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+
+    if sys.stdin.isatty():
+        print(
+            "Error: --*-password-stdin requires piped input.\n"
+            "Example:\n"
+            "  echo \"$REGISTRY_TOKEN\" | "
+            "argus scan --registry-password-stdin --config argus.yml",
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+
+    raw = sys.stdin.read()
+    # Strip a single trailing newline if present (matches
+    # ``docker login --password-stdin`` behavior — handles
+    # ``echo $X | ...`` cleanly without eating multi-line tokens).
+    if raw.endswith("\n"):
+        raw = raw[:-1]
+    if not raw:
+        print(
+            "Error: stdin was empty. The password must be supplied "
+            "as the body of the pipe.",
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+
+    from argus.core.secrets import set_stdin_override
+    set_stdin_override(active[0], raw)
+    return EXIT_SUCCESS
+
+
 def cmd_scan(args: argparse.Namespace) -> int:
     """Execute the scan subcommand.
 
@@ -1215,6 +1305,14 @@ def cmd_scan(args: argparse.Namespace) -> int:
       - zap + --image/--target → DAST lifecycle
       - everything else → source code scanning
     """
+    # Consume any --*-password-stdin flags before further dispatch.
+    # Done first so a usage error surfaces before the scanner-registry
+    # import (which is slower) and so the stdin value is in place for
+    # both the container and DAST lifecycle paths below.
+    rc = _consume_stdin_password_flags(args)
+    if rc != EXIT_SUCCESS:
+        return rc
+
     # Validate scanner name against registry
     if args.scanner and not args.list:
         try:

argus/core/secrets.py

@@ -124,6 +124,47 @@ def resolve_secret(
     return None
 
 
+# ── CLI ``--*-password-stdin`` plumbing ─────────────────────────────
+#
+# A module-level mapping populated by ``argus/cli.py`` after reading
+# a password from stdin (one CLI flag per logical credential slot).
+# Scanner modules look up by *slot* — a stable cross-scanner name —
+# rather than by raw field name so that, e.g., ``registry_password``
+# in container.py and zap.py both pick up the same stdin value but
+# zap's ``auth.password`` does not.
+#
+# Lives in this module (not the CLI) for three reasons:
+#   - the consuming code (resolve_secret callers in scanner modules)
+#     already imports from here;
+#   - tests can clear state via ``clear_stdin_overrides``;
+#   - the stdin value never reaches the per-scanner config dict, so
+#     it can't accidentally leak into argus-audit.json / argus.log
+#     (both of which serialize the per-scanner config block).
+_STDIN_OVERRIDES: dict[str, str] = {}
+
+
+def set_stdin_override(slot: str, value: str) -> None:
+    """Record a stdin-supplied credential under a named slot.
+
+    Slots are stable cross-scanner names — e.g. ``"registry_password"``
+    fills the registry password for every scanner that uses it; an
+    invocation never reaches both ``container.registry_password`` and
+    ``zap.auth.password`` via the same stdin pipe (stdin is a single
+    stream), so distinct slots stay decoupled.
+    """
+    _STDIN_OVERRIDES[slot] = value
+
+
+def get_stdin_override(slot: str) -> str | None:
+    """Return the stdin-supplied value for ``slot``, or None."""
+    return _STDIN_OVERRIDES.get(slot)
+
+
+def clear_stdin_overrides() -> None:
+    """Reset all stdin overrides — test seam, not for production use."""
+    _STDIN_OVERRIDES.clear()
+
+
 def validate_env_var_name(name: str) -> bool:
     """Return ``True`` if ``name`` is a valid POSIX shell identifier."""
     return isinstance(name, str) and bool(_ENV_NAME_VALID.match(name))

argus/scanners/container.py

@@ -174,11 +174,14 @@ def _build_env(self, config: dict) -> dict[str, str]:
         The resolved values are exported to the env vars Trivy / Grype /
         Syft each natively read for registry authentication.
         """
-        from argus.core.secrets import resolve_secret
+        from argus.core.secrets import get_stdin_override, resolve_secret
 
         env = dict(os.environ)
         username = resolve_secret(config, "registry_username")
-        password = resolve_secret(config, "registry_password")
+        password = resolve_secret(
+            config, "registry_password",
+            stdin_override=get_stdin_override("registry_password"),
+        )
 
         if username:
             env["TRIVY_USERNAME"] = username

argus/scanners/zap.py

@@ -135,19 +135,27 @@ def container_env(self, config: dict | None = None) -> dict[str, str | None]:
         context files reference via ``{%username%}`` / ``{%password%}``
         placeholders.
         """
+        from argus.core.secrets import get_stdin_override
+
         config = config or {}
         env: dict[str, str | None] = {}
 
         reg_user = resolve_secret(config, "registry_username")
-        reg_pass = resolve_secret(config, "registry_password")
+        reg_pass = resolve_secret(
+            config, "registry_password",
+            stdin_override=get_stdin_override("registry_password"),
+        )
         if reg_user:
             env["ZAP_REGISTRY_USERNAME"] = reg_user
         if reg_pass:
             env["ZAP_REGISTRY_PASSWORD"] = reg_pass
 
         auth_block = config.get("auth") or {}
         auth_user = resolve_secret(auth_block, "username")
-        auth_pass = resolve_secret(auth_block, "password")
+        auth_pass = resolve_secret(
+            auth_block, "password",
+            stdin_override=get_stdin_override("zap_auth_password"),
+        )
         if auth_user:
             env["ZAP_AUTH_USERNAME"] = auth_user
         if auth_pass:

argus/tests/core/test_secrets.py

@@ -209,3 +209,69 @@ def test_does_not_match_non_secret_strings(self, value):
     def test_non_string_returns_false(self):
         assert looks_like_literal_secret(None) is False
         assert looks_like_literal_secret(12345) is False
+
+
+class TestStdinOverrideSlots:
+    """Slot-based stdin override registry — populated by the CLI's
+    ``--*-password-stdin`` flags, consumed by scanners via
+    ``get_stdin_override(slot)``.
+    """
+
+    def setup_method(self):
+        from argus.core.secrets import clear_stdin_overrides
+        clear_stdin_overrides()
+
+    def teardown_method(self):
+        # Process-level state: tests must reset to avoid leaking
+        # values to other tests in the same pytest run.
+        from argus.core.secrets import clear_stdin_overrides
+        clear_stdin_overrides()
+
+    def test_set_and_get_roundtrip(self):
+        from argus.core.secrets import get_stdin_override, set_stdin_override
+
+        set_stdin_override("registry_password", "from-stdin")
+        assert get_stdin_override("registry_password") == "from-stdin"
+
+    def test_unset_slot_returns_none(self):
+        from argus.core.secrets import get_stdin_override
+
+        assert get_stdin_override("never_set") is None
+
+    def test_distinct_slots_dont_collide(self):
+        from argus.core.secrets import get_stdin_override, set_stdin_override
+
+        set_stdin_override("registry_password", "reg-pass")
+        set_stdin_override("zap_auth_password", "app-pass")
+
+        assert get_stdin_override("registry_password") == "reg-pass"
+        assert get_stdin_override("zap_auth_password") == "app-pass"
+
+    def test_clear_resets_all_slots(self):
+        from argus.core.secrets import (
+            clear_stdin_overrides,
+            get_stdin_override,
+            set_stdin_override,
+        )
+
+        set_stdin_override("registry_password", "x")
+        set_stdin_override("zap_auth_password", "y")
+        clear_stdin_overrides()
+
+        assert get_stdin_override("registry_password") is None
+        assert get_stdin_override("zap_auth_password") is None
+
+    def test_resolve_secret_uses_stdin_override_arg(self):
+        """The resolver's existing ``stdin_override=`` kwarg still wins
+        even when nothing is set in the slot registry. Slot lookup is
+        the caller's responsibility — the resolver itself does not
+        introspect the registry."""
+        from argus.core.secrets import resolve_secret
+
+        result = resolve_secret(
+            {"registry_password_env": "ANY"},
+            "registry_password",
+            env={},
+            stdin_override="explicit-override",
+        )
+        assert result == "explicit-override"