docs: explain how dashboard settings override workflow inputs

[David Larsen (dc-larsen)]

Summary

When an Enterprise organization's dashboard configuration loads, Socket Basics merges it over the INPUT_* environment variables that carry the action's with: inputs. Dashboard fields that were never filled in come back from the settings API as '' or false, so they replace the workflow's values too. A blank Dockerfiles field wipes dockerfiles: and no Dockerfile is scanned.

The docs said dashboard values override "overlapping" with: values and that the workflow needs no changes. Two examples (Container Security Pipeline and Dockerfile Auto-Discovery) scan nothing for these organizations, with no error. This PR documents the actual precedence and gives a working pattern for per-repository values. It describes current behavior only. Whether blank dashboard fields should override workflow inputs at all is a separate code question.

Changes

• New section in docs/github-action.md, Dashboard Settings and Workflow Inputs:
  • when the dashboard configuration loads (Enterprise plan, Socket Basics enabled, socket-basics scope)
  • which settings blank fields override
  • the exceptions: blank rule lists are skipped, blank notifier fields and GitHub token fall back to the workflow, and some inputs have no dashboard field
  • the log lines that show which mode ran
• Setting Values Per Repository: run docker://ghcr.io/socketdev/socket-basics:<version> with args: so --dockerfiles and --images apply after the dashboard merge. Also covers the two differences from the action: the action.yml rule-list defaults don't apply, and the image tag is bumped by hand.
• Examples: IMPORTANT callouts on the Container Security Pipeline and Dockerfile Auto-Discovery examples. The auto-discovery callout includes the replacement step.
• Container scanning: dockerfiles runs trivy config (misconfigurations only). Base-image vulnerabilities need the built image in container_images. Paths are literal, comma-separated and repository-relative.
• Precedence: docs/parameters.md now says that with: inputs are environment variables, when the dashboard layer applies, and how blank fields behave.
• README and Quick Start: replace "no workflow changes needed" with the Enterprise condition and the precedence note.
• Troubleshooting: new "Workflow Inputs Have No Effect" entry covering both Trivy log shapes.

Testing

• pytest -q tests/: 489 passed.
• python3 scripts/check_release_docs.py --check and python3 scripts/sync_release_version.py --check: in sync at 3.4.0. The new docker:// references are tag-only, so the release docs sync picks them up.
• All 35 YAML blocks in the edited files parse, including the one inside the auto-discovery callout. Every new anchor resolves.
• I checked the behavior claims against 3.4.0 by feeding a simulated Enterprise dashboard response through create_config_from_args (22/22 checks pass). The response used '' and false for unset keys, matching the settings endpoint's defaults.
  • Blank Dockerfiles and Container Images fields wipe the inputs. With trivy_vuln_enabled off, Trivy never loads. With it on, Trivy logs No Dockerfiles specified, skipping Trivy Dockerfile scanning.
  • Switched-off toggles beat true inputs: SAST language, secrets, verbose and console output.
  • A blank <language>_enabled_rules is skipped. trivy_vuln_enabled and changed_files come from the workflow.
  • A blank Slack field and a blank GitHub token fall back to the environment.
  • --dockerfiles and --images beat blank dashboard fields, and the other dashboard settings still apply. Without the action.yml defaults, Java uses the 19-rule list from connectors.yaml.
• The docker:// step pattern with --dockerfiles and --images has been confirmed working in a GitHub Actions workflow on 3.4.0.
• docker buildx imagetools inspect ghcr.io/socketdev/socket-basics:3.4.0 prints the published digest.

---

Note

Low Risk
Documentation-only changes with no runtime or configuration code modifications.

Overview
This PR corrects misleading guidance that Enterprise customers need no workflow changes when using the Socket Dashboard. It documents that loaded dashboard config wins over with: inputs, including empty dashboard fields and off toggles, which can silently disable scanners (notably blank Dockerfiles / Container Images wiping dockerfiles and container_images).

docs/github-action.md adds Dashboard Settings and Workflow Inputs (load conditions, override rules, exceptions, log lines), Setting Values Per Repository via docker://ghcr.io/socketdev/socket-basics with args: for per-repo overrides, IMPORTANT notes on container and auto-discovery examples, clearer dockerfiles vs container_images behavior, and troubleshooting for inputs that seem ignored.

docs/parameters.md updates Configuration Precedence so action inputs map to INPUT_* env vars and documents blank-field behavior plus the CLI-only override path.

README.md aligns Quick Start and Enterprise copy with the same precedence story and adds a troubleshooting bullet.

^{Reviewed by Cursor Bugbot for commit 2b8f601. Configure here.}