feat: align install guides with the CLI and declare the documented action inputs

[lelia]

Summary

Socket Basics can be run as a GitHub Action, as a Docker image, or as a native install, and each surface spells the same setting differently (--python on the CLI, python_sast_enabled as an action input, INPUT_PYTHON_SAST_ENABLED in the environment). This PR brings the guides for all three paths into line with the current CLI, action.yml and configuration loader, adds a single reference table for translating between them, declares the action inputs the documentation already describes so they behave like the CLI flags, and adds the CLI flags the docs were missing.

Changes

Documentation (README.md, docs/)

• CLI examples in the local-install, pre-commit and README guides now use the flag names that socket-basics --help prints.
• New Name Mapping section in docs/parameters.md: every setting as CLI flag, GitHub Action input, environment variable and JSON key, generated from connectors.yaml, notifications.yaml and action.yml. Also clarifies that the API key is environment-only and that --repo names the repository, not the organization.
• Docker guide: results are written inside the workspace so the dashboard upload succeeds; a recipe for PR comments from a plain docker run (GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_PR_NUMBER); GitLab and Jenkins examples override the image entrypoint; --entrypoint used for the bundled-tool version checks; an Image Variants section explaining the standard image and the -heavy variant; guidance for large repositories and facts-file size.
• GitHub Action guide: container-scanning section updated for the bundled Trivy scanner; the Dockerfile auto-discovery example passes the discovered files through; the configuration reference lists only declared inputs; expanded troubleshooting for PR comments and dashboard results; environment-variable behavior described precisely.
• JSON configuration examples use the keys the loader reads; S3 variable names and --config precedence match the code; the local-install guide states the Python 3.10 requirement and the npm install path for the Socket CLI; bundled scanner versions and one action reference updated to current values; dead links to configuration.md point at the parameters reference.
• docs/alert-quality-improvement-plan.md, a planning draft from a hackathon branch, is removed from the repository and tracked as CE-447 instead.

Action and CLI

• --version and --socket-org flags. --socket-org is the CLI equivalent of the socket_org input / SOCKET_ORG; the API key remains environment-only by design.
• New action inputs verbose, console_tabular_enabled and console_json_enabled, delivered as INPUT_VERBOSE / INPUT_CONSOLE_TABULAR_ENABLED / INPUT_CONSOLE_JSON_ENABLED and honored from the environment like the matching CLI flags.
• New action inputs jira_url and jira_project (the names used in the docs; server and project remain as aliases), ms_sentinel_shared_key (alias of ms_sentinel_key), opengrep_notification_method and trufflehog_notification_method (notification_method remains as an alias).
• Removed the workspace and GITHUB_API_URL action inputs, which had no effect (the scan root is always GITHUB_WORKSPACE; GITHUB_API_URL is provided by the runner). Workflows that still set them receive an "Unexpected input" warning and otherwise behave as before.
• The Sentinel and Sumo Logic notifiers read the parameter names declared in notifications.yaml, so CLI flags, action inputs and dashboard values reach them alongside the existing environment variables.

Tooling

• scripts/check_release_docs.py (run by prep_release.py and CI) also verifies that action references use an exact release tag and that TruffleHog, OpenGrep and Trivy versions quoted in the guides match the Dockerfile pins; --write updates both.
• New tests keep action.yml in step with connectors.yaml / notifications.yaml (every parameter's INPUT_* variable is produced, every env mapping references a declared input) and cover the new flags and notifier parameters.

Testing

• pytest: 363 passed.
• python3 scripts/check_release_docs.py --check: in sync (release 3.1.0; tool pins TruffleHog 3.96.0, OpenGrep 1.26.0, Trivy 0.73.0).
• socket-basics --version, --socket-org and INPUT_VERBOSE=true verified end to end against the local install.
• Every YAML/JSON block in the guides parses; every internal anchor resolves; every uses: SocketDev/socket-basics@... reference is pinned to v3.1.0 or <sha>.
• Runner behavior for undeclared inputs confirmed against the actions/runner source.

Release note

The new flags and inputs make this a minor release. Per the usual flow, version files are not bumped here; a follow-up release-prep PR (prep_release.py --version 3.2.0) will do that after merge, and its docs sync now also covers the scanner pins.

Fixes CE-445

---

Note

Medium Risk
Removes two action inputs (minor workflow breakage) and changes how org, logging, and SIEM/Sumo credentials are resolved across surfaces; behavior is mostly additive with aliases but misconfiguration could affect uploads and notifications.

Overview
Aligns how settings are exposed across the CLI, GitHub Action, environment variables, and JSON/dashboard config, with a generated name mapping in docs/parameters.md and broad guide updates so examples match socket-basics --help and bundled Trivy behavior.

CLI and config: Adds --version and --socket-org (API key stays env-only). INPUT_VERBOSE, INPUT_CONSOLE_TABULAR_ENABLED, and INPUT_CONSOLE_JSON_ENABLED now load like their CLI flags; merged verbose can raise log level after config merge. --socket-org is passed into dashboard config loading and re-applied after merge.

GitHub Action (action.yml): New inputs for logging, Jira (jira_url / jira_project with server / project aliases), Sentinel (ms_sentinel_shared_key), and OpenGrep/TruffleHog notification methods. Removes no-op workspace and GITHUB_API_URL inputs (existing workflows get an “Unexpected input” warning only).

Notifiers: Microsoft Sentinel and Sumo Logic read ms_sentinel_* / sumologic_endpoint from CLI, action inputs, and app config in addition to legacy env names.

Tooling and tests: check_release_docs.py also syncs Dockerfile scanner pins and exact action tags; new tests guard action.yml ↔ YAML parameter env mappings and the new flags/notifier params. Removes draft docs/alert-quality-improvement-plan.md.

^{Reviewed by Cursor Bugbot for commit 8ee7b62. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: OpenGrep notify input is overwritten
  • OpenGrep and TruffleHog now store notify settings under unique config keys, so an empty Action TruffleHog input no longer wipes OpenGrep's notification_method.

Or push these changes by commenting:

@cursor push b321dc967d

Preview (b321dc967d)

diff --git a/socket_basics/connectors.yaml b/socket_basics/connectors.yaml
--- a/socket_basics/connectors.yaml
+++ b/socket_basics/connectors.yaml
@@ -145,7 +145,7 @@
         env_variable: INPUT_ERLANG_SAST_ENABLED
         type: bool
         default: false
-      - name: notification_method
+      - name: opengrep_notification_method
         option: --opengrep-notify
         description: "Notification method for OpenGrep (e.g., console, slack)"
         env_variable: INPUT_OPENGREP_NOTIFICATION_METHOD
@@ -410,7 +410,7 @@
         env_variable: INPUT_TRUFFLEHOG_EXCLUDE_DIR
         type: str
         default: ""
-      - name: notification_method
+      - name: trufflehog_notification_method
         option: --trufflehog-notify
         description: "Notification method for TruffleHog (e.g., console, slack)"
         env_variable: INPUT_TRUFFLEHOG_NOTIFICATION_METHOD

diff --git a/tests/test_notification_method_env.py b/tests/test_notification_method_env.py
new file mode 100644
--- /dev/null
+++ b/tests/test_notification_method_env.py
@@ -1,0 +1,43 @@
+"""OpenGrep and TruffleHog notify inputs must not share a config key.
+
+GitHub Actions always exports every ``runs.env`` entry, so an unset
+``trufflehog_notification_method`` arrives as ``INPUT_TRUFFLEHOG_NOTIFICATION_METHOD=""``.
+That empty string must not wipe a real OpenGrep notify setting.
+"""
+
+from socket_basics.core.config import load_config_from_env
+from socket_basics.core.notification.manager import NotificationManager
+
+NOTIFY_ENV_VARS = (
+    "INPUT_OPENGREP_NOTIFICATION_METHOD",
+    "INPUT_TRUFFLEHOG_NOTIFICATION_METHOD",
+    "INPUT_TRIVY_NOTIFICATION_METHOD",
+)
+
+
+def test_empty_trufflehog_action_input_does_not_wipe_opengrep_notify(monkeypatch):
+    for name in NOTIFY_ENV_VARS:
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("INPUT_OPENGREP_NOTIFICATION_METHOD", "slack")
+    # Unset Action inputs are forwarded as empty strings, not omitted.
+    monkeypatch.setenv("INPUT_TRUFFLEHOG_NOTIFICATION_METHOD", "")
+
+    config = load_config_from_env()
+
+    assert config.get("opengrep_notification_method") == "slack"
+    assert not config.get("trufflehog_notification_method")
+
+    nm = NotificationManager(
+        {
+            "notifiers": {
+                "slack": {
+                    "module_path": "socket_basics.core.notification.slack_notifier",
+                    "class": "SlackNotifier",
+                    "parameters": [],
+                }
+            }
+        },
+        app_config=config,
+    )
+    nm.load_from_config()
+    assert any(getattr(n, "name", "") == "slack" for n in nm.notifiers)

_{You can send follow-ups to the cloud agent here.}

[lelia]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8ee7b62. Configure here.}

[Erika Tharp (poppoerika)]

LGTM