SocketDev · David Larsen (dc-larsen) · Oct 5, 2026
@@ -50,7 +50,7 @@ jobs:
 > with a review gate. See [docs/github-action.md](docs/github-action.md#pinning-strategies)
 > for the full explanation and Dependabot setup.
 
-**That's it!** With a properly scoped `SOCKET_SECURITY_API_KEY`, all scanning configurations are managed through the [Socket Dashboard](https://socket.dev/dashboard) — no workflow changes needed. See [Required API Token Scopes](#required-api-token-scopes) for details.
+**That's it!** On a Socket Enterprise organization with Socket Basics enabled, a properly scoped `SOCKET_SECURITY_API_KEY` loads your scanning configuration from the [Socket Dashboard](https://socket.dev/dashboard), so the workflow needs no scanner inputs. Dashboard settings take precedence over scanner inputs in the workflow, including dashboard fields left blank (see [Dashboard Settings and Workflow Inputs](docs/github-action.md#dashboard-settings-and-workflow-inputs)). Without dashboard configuration, turn scanners on with [action inputs](docs/github-action.md#common-scanning-options). See [Required API Token Scopes](#required-api-token-scopes) for details.
 
 ### What You Get
 
@@ -154,7 +154,7 @@ Socket Enterprise customers can configure Socket Basics directly from the [Socke
 
 ![Socket Basics Settings](docs/screenshots/socket_basics_settings.png)
 
-Configure scanning policies, notification channels, and rule sets for your entire organization in one place. Your settings are automatically synchronized when you provide `SOCKET_SECURITY_API_KEY` and `SOCKET_ORG`.
+Configure scanning policies, notification channels, and rule sets for your entire organization in one place. Socket Basics loads these settings on every run when its API key has the `socket-basics` scope, and they take precedence over the matching workflow inputs, including fields you leave blank. See [Dashboard Settings and Workflow Inputs](docs/github-action.md#dashboard-settings-and-workflow-inputs) for the exceptions and for setting values per repository.
 
 ![Socket Basics Section Config](docs/screenshots/socket_basics_section_config.png)
 
@@ -270,6 +270,9 @@ Add new connectors by:
 - Verify your Socket Enterprise subscription is active
 - If you see `Insufficient permissions`, confirm your API token has the scopes required for your configuration mode (see [Required API Token Scopes](#required-api-token-scopes))
 
+**Workflow inputs have no effect, or Dockerfile and image scanning finds nothing:**
+- If the log shows `Loaded Socket Basics API configuration (overrides environment defaults)`, the dashboard configuration took precedence over your inputs, blank fields included (see [Dashboard Settings and Workflow Inputs](docs/github-action.md#dashboard-settings-and-workflow-inputs))
+
 **Notifier errors:**
 - Check that notification credentials (Slack webhook, Jira token, etc.) are properly configured
 - Remember: Notifiers require Socket Enterprise

@@ -51,7 +51,9 @@ jobs:
           socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 ```
 
-With just your `SOCKET_SECURITY_API_KEY`, all scanning configurations are managed through the [Socket Dashboard](https://socket.dev/dashboard) — no workflow changes needed.
+On a Socket Enterprise organization with Socket Basics enabled, this is the whole workflow: the API key loads your scanning configuration from the [Socket Dashboard](https://socket.dev/dashboard). Dashboard settings take precedence over scanner inputs you add to `with:`, including dashboard fields you leave blank. See [Dashboard Settings and Workflow Inputs](#dashboard-settings-and-workflow-inputs).
+
+Without dashboard configuration, every scanner input defaults to off, so turn on the scanners you want with the inputs under [Common Scanning Options](#common-scanning-options).
 
 ## Performance and Caching
 
@@ -263,6 +265,13 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
     trivy_vuln_enabled: 'true'
 ```
 
+`dockerfiles` checks each Dockerfile for misconfigurations with `trivy config`.
+It does not report vulnerabilities in the base image or in packages the build
+installs. For those, build the image and list it in `container_images`, which
+runs `trivy image`. Both inputs take literal, comma-separated values. Dockerfile
+paths are relative to the repository root, wildcards are not expanded, and a
+path that does not exist is skipped with a `Dockerfile not found` warning.
+
 > [!NOTE]
 > Trivy is bundled in the pre-built action image (a Socket-built distribution,
 > rebuilt from unmodified upstream source and pinned by digest), so these inputs
@@ -472,6 +481,89 @@ Your workflow will automatically use the settings configured in the dashboard.
 
 ![Socket Basics Section Configuration](screenshots/socket_basics_section_config.png)
 
+### Dashboard Settings and Workflow Inputs
+
+When the dashboard configuration loads, it takes precedence over the action's
+`with:` inputs. The action passes every input to the scanner as an `INPUT_*`
+environment variable, and dashboard settings are applied on top of environment
+variables (see [Configuration Precedence](parameters.md#configuration-precedence)).
+
+The dashboard configuration loads when all three of these are true:
+
+- The organization is on a Socket Enterprise plan.
+- Socket Basics is enabled for the organization.
+- The API key has the `socket-basics` scope.
+
+Fields you leave blank in the dashboard still count. The dashboard sends a blank
+field as an empty value and a switched-off toggle as `false`, and either one
+replaces what the workflow set. This covers the SAST language and rule settings,
+secret scanning, Socket Tier 1, the **Container Images** and **Dockerfiles**
+fields, console output and verbose logging. For example, if the **Dockerfiles**
+field is blank, a workflow that sets `dockerfiles: 'Dockerfile'` scans no
+Dockerfiles.
+
+The exceptions:
+
+- A blank `<language>_enabled_rules` or `<language>_disabled_rules` field is
+  skipped, so the workflow's value or the action's default list applies.
+- A blank notification field (Slack, Jira, Microsoft Teams, generic webhook,
+  Microsoft Sentinel, Sumo Logic) falls back to the workflow's value, and so does
+  a blank GitHub token. A filled-in dashboard field still wins.
+- These inputs have no dashboard field, so the workflow's value applies:
+  `changed_files`, `scan_files`, `scan_all`, `use_custom_sast_rules`,
+  `custom_sast_rule_path`, `sast_ignore_overrides`, `trivy_vuln_enabled` and the
+  PR comment and label inputs.
+
+To check which configuration a run used, look for one of these lines in the step
+log:
+
+| Log line | What it means |
+|---|---|
+| `Loaded Socket Basics API configuration (overrides environment defaults)` | The dashboard configuration loaded and takes precedence over your `with:` inputs |
+| `Loaded Socket plan metadata (free/non-enterprise mode; no dashboard overrides)` | No dashboard configuration loaded, so your `with:` inputs apply |
+| `Error loading Socket Basics config: ...` | The dashboard configuration could not be loaded, so your `with:` inputs apply. The message says why. |
+
+#### Setting Values Per Repository
+
+Dashboard values apply to every repository in the organization, so put a value
+in the dashboard when it is the same everywhere. A Dockerfile path that does not
+exist in a repository is skipped with a `Dockerfile not found` warning, so one
+list of common paths can serve every repository.
+
+For values that differ per repository, such as Dockerfile paths or images built
+earlier in the job, pass CLI flags. CLI flags are applied after the dashboard
+configuration, but the action does not accept them, so run the action's image
+directly as a step:
+
+```yaml
+- name: Build image
+  run: docker build -t myapp:${{ github.sha }} .
+
+- name: Run Socket Basics
+  uses: docker://ghcr.io/socketdev/socket-basics:3.4.0
+  env:
+    SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
+  with:
+    args: --dockerfiles Dockerfile,docker/Dockerfile.prod --images myapp:${{ github.sha }}
+```
+
+Only the flags you pass take precedence. Every other setting still comes from
+the dashboard. Running the image directly differs from the action in two ways:
+
+- The action's default rule lists (`<language>_enabled_rules` in
+  [`action.yml`](../action.yml)) don't apply. Where the dashboard's rule-list
+  fields are blank, SAST uses the image's own defaults from
+  [`connectors.yaml`](../socket_basics/connectors.yaml), which include more rules
+  for some languages.
+- The step isn't tied to an action version, so update the image tag yourself
+  when you upgrade. To pin by digest, append `@sha256:<digest>` to the image.
+  `docker buildx imagetools inspect ghcr.io/socketdev/socket-basics:3.4.0`
+  prints the digest.
+
+See the [Parameters Reference](parameters.md) for every CLI flag.
+
 ### Notification Integrations
 
 All notification integrations require Socket Enterprise.
@@ -641,6 +733,13 @@ jobs:
 > rebuilt from unmodified upstream source and pinned by digest), so the
 > container-scanning inputs below work out of the box with no Trivy install step.
 
+> [!IMPORTANT]
+> When your organization's dashboard configuration loads, its **Container
+> Images** and **Dockerfiles** fields take precedence over `container_images`
+> and `dockerfiles` in this example, even when those fields are blank. Pass the
+> values as CLI flags instead, as shown in
+> [Setting Values Per Repository](#setting-values-per-repository).
+
 ```yaml
 name: Container Security
 on:
@@ -682,6 +781,27 @@ jobs:
 
 For repositories with multiple Dockerfiles across different directories, you can automatically discover them instead of manually listing each path.
 
+> [!IMPORTANT]
+> This example passes the discovered paths through the `dockerfiles` input. When
+> your organization's dashboard configuration loads, the dashboard's
+> **Dockerfiles** field takes precedence over that input, even when the field is
+> blank, and the discovered paths are never scanned. In that case, replace the
+> `Run Socket Basics` step in the `security-scan` job with:
+>
+> ```yaml
+> - name: Run Socket Basics
+>   uses: docker://ghcr.io/socketdev/socket-basics:3.4.0
+>   env:
+>     SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+>     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+>     GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
+>   with:
+>     args: --dockerfiles ${{ needs.discover-dockerfiles.outputs.dockerfiles }} --verbose
+> ```
+>
+> [Setting Values Per Repository](#setting-values-per-repository) covers how
+> this step differs from the action.
+
 ```yaml
 name: Security Scan with Dockerfile Auto-Discovery
 on:
@@ -810,8 +930,12 @@ jobs:
 ```
 
 Important behavior:
-- `socket_security_api_key` + `socket_org` enables dashboard config loading.
-- Dashboard/API settings override overlapping `with:` values.
+- When the dashboard configuration loads, its SAST language toggles,
+  `all_rules_enabled` and rule lists take precedence over these `with:` values,
+  including fields left blank. A blank rule list is the exception and is skipped.
+  `use_custom_sast_rules`, `custom_sast_rule_path` and `sast_ignore_overrides`
+  have no dashboard field and come from the workflow. See
+  [Dashboard Settings and Workflow Inputs](#dashboard-settings-and-workflow-inputs).
 - `<language>_enabled_rules` is an allowlist and can suppress custom rule IDs.
 - `all_rules_enabled: 'true'` disables allowlist filtering for enabled languages.
 
@@ -1002,6 +1126,27 @@ env:
   run: echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u "${{ secrets.DOCKER_USERNAME }}" --password-stdin
 ```
 
+### Workflow Inputs Have No Effect
+
+**Problem:** A scanner turned on in `with:` doesn't run, or Dockerfile and image
+scanning reports nothing even though `dockerfiles` or `container_images` is set.
+
+**Likely cause:** The dashboard configuration loaded and took precedence over
+those inputs, blank fields included. When the **Dockerfiles** and **Container
+Images** fields are blank, Trivy doesn't load, so the log has no
+`Successfully loaded connector: trivy` line. If `trivy_vuln_enabled` is on,
+Trivy loads for the filesystem scan and logs
+`No Dockerfiles specified, skipping Trivy Dockerfile scanning` instead.
+
+**How to confirm:** Look for `Loaded Socket Basics API configuration (overrides
+environment defaults)` in the step log, then check the matching fields on the
+dashboard's Socket Basics settings page.
+
+**Solutions:**
+1. Set the value in the dashboard if it is the same for every repository.
+2. Pass it as a CLI flag by running the image directly, as shown in
+   [Setting Values Per Repository](#setting-values-per-repository).
+
 ### Enterprise Features Not Working
 
 **Problem:** Dashboard configuration or notifications not working.

@@ -947,17 +947,26 @@ The output file name is a CLI-only option (`--output`); set
 Configuration is merged in the following order (later sources override earlier ones):
 
 1. Default values
-2. Environment variables
-3. Socket Basics API configuration (when available and no `--config` file is used)
+2. Environment variables, including GitHub Action inputs (the action passes each `with:` input as an `INPUT_*` variable)
+3. Socket Basics dashboard configuration (when the organization is on an Enterprise plan with Socket Basics enabled, the API key has the `socket-basics` scope, and no `--config` file is used)
 4. JSON configuration file (via `--config`)
 5. Command-line arguments
 
+Dashboard configuration overrides environment variables even for fields left
+blank in the dashboard: a blank field or a switched-off toggle replaces the
+environment value. Blank `<language>_enabled_rules` and
+`<language>_disabled_rules` fields are skipped, and blank notifier fields fall
+back to their environment variables. The GitHub Action passes no command-line
+arguments, so to override a dashboard value from a workflow, run the image
+directly with CLI flags. See
+[Dashboard Settings and Workflow Inputs](github-action.md#dashboard-settings-and-workflow-inputs).
+
 **Example:**
 ```bash
-# Environment sets python_sast_enabled=true
-# Dashboard/API sets python_sast_enabled=false
+# Environment sets python_sast_enabled=true and dockerfiles=Dockerfile
+# Dashboard sets python_sast_enabled=false and leaves the Dockerfiles field blank
 # CLI has --javascript
-# Result: JavaScript enabled, Python follows dashboard/API value, other settings from env/API
+# Result: JavaScript enabled, Python disabled, no Dockerfiles scanned
 socket-basics --javascript
 ```