ci: wire govulncheck job to the action (missed in prior commit)

The previous commit deleted the wrapper files but a failed `git add`
pathspec dropped the security.yml/CODEOWNERS/docs edits, leaving the
job pointing at the now-deleted wrapper. This commits the actual
govulncheck-action + SARIF-upload job body and the doc/CODEOWNERS
updates.

Author: otavio

.github/CODEOWNERS

@@ -3,7 +3,6 @@ api/ @shellhub-io/backend-owners
 ssh/ @shellhub-io/backend-owners
 ui/ @shellhub-io/frontend-owners
 
-# Security allowlist and scanner ignore files — reviewed by team lead.
+# Security scanner ignore files — reviewed by team lead.
 .trivyignore @shellhub-io/team-lead
-.govulncheck-allow.txt @shellhub-io/team-lead
 .semgrepignore @shellhub-io/team-lead

.github/workflows/security.yml

@@ -29,45 +29,59 @@ jobs:
       matrix:
         include:
           - module: .
-            extra_args: ""
+            sarif_name: root
+            tags: ""
           - module: api
-            extra_args: ""
+            sarif_name: api
+            tags: ""
+          # agent/ssh build-tag coverage relies on GOFLAGS being forwarded to go/packages
           - module: agent
-            extra_args: "-tags docker"
+            sarif_name: agent
+            tags: docker
           - module: ssh
-            extra_args: "-tags internal_api"
+            sarif_name: ssh
+            tags: internal_api
           - module: cli
-            extra_args: ""
+            sarif_name: cli
+            tags: ""
           - module: gateway
-            extra_args: ""
+            sarif_name: gateway
+            tags: ""
           - module: openapi
-            extra_args: ""
+            sarif_name: openapi
+            tags: ""
           - module: tests
-            extra_args: ""
+            sarif_name: tests
+            tags: ""
 
     runs-on: ubuntu-latest
 
     steps:
       - name: Check out code
         uses: actions/checkout@v6
 
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version-file: go.mod
-
-      - name: Install govulncheck
-        run: go install golang.org/x/vuln/cmd/govulncheck@latest
-
-      - name: Build govulncheck wrapper
-        run: |
-          ( cd "$GITHUB_WORKSPACE/.github" && go build -o "$RUNNER_TEMP/govulncheck-filter" ./govulncheck/cmd )
-
       - name: Run govulncheck
-        run: |
-          cd "${{ matrix.module }}"
-          govulncheck -json ${{ matrix.extra_args }} ./... | \
-            "$RUNNER_TEMP/govulncheck-filter" "$GITHUB_WORKSPACE/.govulncheck-allow.txt"
+        uses: golang/govulncheck-action@v1
+        env:
+          # govulncheck honors GOFLAGS through go/packages for build-tag coverage
+          GOFLAGS: ${{ matrix.tags != '' && format('-tags={0}', matrix.tags) || '' }}
+        with:
+          go-version-file: ${{ matrix.module == '.' && 'go.mod' || format('{0}/go.mod', matrix.module) }}
+          work-dir: ${{ matrix.module }}
+          go-package: ./...
+          output-format: sarif
+          output-file: govulncheck-${{ matrix.sarif_name }}.sarif
+          repo-checkout: false
+
+      # Vuln gating is performed by GitHub's native "Code scanning results" PR check
+      # (identical to CodeQL/Semgrep); this upload step is the success signal for
+      # security-gate — govulncheck's own exit code does NOT block the PR.
+      - name: Upload SARIF report
+        if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: govulncheck-${{ matrix.sarif_name }}.sarif
+          category: govulncheck-${{ matrix.sarif_name }}
 
   trivy-image:
     name: trivy-image (${{ matrix.image }})

SECURITY-SCANNING.md

@@ -32,7 +32,7 @@ all three `security-gate` jobs report success (or skipped).
 
 | Workflow file | Tool | What it scans | Runs on |
 |---|---|---|---|
-| `.github/workflows/security.yml` | **govulncheck** | Known Go CVEs in all modules (`.`, `api`, `agent`, `ssh`, `cli`, `gateway`, `openapi`, `tests`) | PR + push to master + weekly |
+| `.github/workflows/security.yml` | **govulncheck** | Known Go CVEs in all modules (`.`, `api`, `agent`, `ssh`, `cli`, `gateway`, `openapi`, `tests`); SARIF uploaded to GitHub Security tab | PR + push to master + weekly |
 | `.github/workflows/security.yml` | **Trivy (image)** | OS/library CVEs in service images (`api`, `ssh`, `gateway`, `cli`, `ui`, `agent`) | PR + push to master + weekly |
 | `.github/workflows/semgrep.yml` | **Semgrep** | Static analysis via `p/golang`, `p/dockerfile`, `p/ci`; PR mode uses `--baseline-ref` so only _new_ findings block | PR + push to master + weekly |
 | `.github/workflows/codeql.yml` | **CodeQL** | Semantic Go analysis across all modules; SARIF uploaded to GitHub Security tab | PR + push to master + weekly |
@@ -45,7 +45,7 @@ those lack the necessary `security-events: write` permission).
 
 ## Baseline suppression files
 
-Three baseline files gate new suppressions behind a team-lead code-owner review
+Two baseline files gate new suppressions behind a team-lead code-owner review
 (see `.github/CODEOWNERS`).
 
 ### `.trivyignore` — Trivy CVE suppression
@@ -64,22 +64,6 @@ Three baseline files gate new suppressions behind a team-lead code-owner review
    `@shellhub-io/team-lead` for mandatory review.
 4. Schedule a quarterly review to remove the entry once the vulnerability is patched.
 
-### `.govulncheck-allow.txt` — govulncheck allowlist
-
-```
-# GO-YYYY-NNNN reachability=called|imported # owner: @handle — justification; tracked: ISSUE-123
-```
-
-Fields:
-
-- `GO-YYYY-NNNN` — Go vulnerability database ID (required).
-- `reachability=called` — the vulnerable function appears in the call graph.
-- `reachability=imported` — the vulnerable package is imported but the function is not called.
-
-**How to add an entry:** follow the same owner + justification + quarterly-review process as
-`.trivyignore`.  Stale entries (where the vulnerability no longer appears in findings) cause
-CI to fail — remove them promptly.
-
 ### `.semgrepignore` — Semgrep path exclusion
 
 ```
@@ -93,7 +77,7 @@ generated mocks).  **Do not suppress production source paths** — fix the findi
 
 ## Inline suppression conventions
 
-### `#nosec` (gosec / govulncheck)
+### `#nosec` (gosec)
 
 Append `//nolint:gosec` or `#nosec GXXX` directly on the line that triggers the finding:
 
@@ -103,6 +87,20 @@ conn, err := tls.Dial("tcp", addr, cfg) //nolint:gosec // G402: minimum TLS vers
 
 Always include a short rationale after the directive.
 
+### govulncheck — suppressing a finding
+
+govulncheck findings are surfaced as alerts in the GitHub Security tab (SARIF-based).
+To suppress a known, accepted vulnerability:
+
+1. Open the alert in the **Security → Code scanning alerts** tab.
+2. Click **Dismiss alert** and choose a reason (e.g. "Used in tests", "Risk accepted",
+   "False positive") along with a brief comment identifying the owner and justification.
+3. Dismissed alerts are audited and visible to the team in the Security tab.  There is no
+   separate suppression file — suppression lives entirely in GitHub code scanning.
+
+> **Note:** The `agent` and `ssh` modules scan with build tags (`docker` and `internal_api`
+> respectively) via the `GOFLAGS` environment variable forwarded to `go/packages`.
+
 ### `# nosemgrep: <rule-id> -- <reason>` (Semgrep)
 
 Add a comment on the line **above** the offending code using the exact format
@@ -161,10 +159,11 @@ branch or workflow:
    do not yet mark them as required checks in branch protection.  Let the scans accumulate
    data for at least one week.
 
-2. **Seed the baseline files** — review findings from step 1 and populate `.trivyignore`,
-   `.govulncheck-allow.txt`, and `.semgrepignore` with justified suppressions for any
-   pre-existing issues that cannot be fixed immediately.  Each entry requires an owner and
-   justification comment.
+2. **Seed the baseline files** — review findings from step 1 and populate `.trivyignore`
+   and `.semgrepignore` with justified suppressions for any pre-existing issues that cannot
+   be fixed immediately.  Each entry requires an owner and justification comment.  For
+   govulncheck findings, dismiss the alert in the GitHub Security tab with a reason — no
+   separate file is needed.
 
 3. **Flip to blocking-on-new** — configure Semgrep to run with `--baseline-ref origin/master`
    on PRs (already the default in `semgrep.yml`) so that only _new_ findings introduced by
@@ -175,7 +174,7 @@ branch or workflow:
    GitHub repository settings → Branches → Branch protection rules for `master`:
    - Under "Require status checks to pass before merging", add **`security-gate`** (the
      exact frozen name) from each of the three workflows (Security, Semgrep, CodeQL).
-   - Enable **"Require review from Code Owners"** so that changes to `.trivyignore`,
-     `.govulncheck-allow.txt`, and `.semgrepignore` always go through `@shellhub-io/team-lead`.
+   - Enable **"Require review from Code Owners"** so that changes to `.trivyignore`
+     and `.semgrepignore` always go through `@shellhub-io/team-lead`.
 
 > **Note:** Steps 1–3 are performed by contributors; step 4 requires a repository admin.