feat(linter): add workflow permissions analysis with actions-permissions

- Add new permissions-analysis job to linter.yml workflow
- Job runs GitHubSecurityLab/actions-permissions to analyze workflow permissions
- Follows same pattern as actions-pinning job for consistency
- Uses minimal permissions (contents: read)
- Analyzes same workflow files as defined in action-files input
- Updates documentation to reflect new permissions analysis feature

Co-authored-by: neilime <314088+neilime@users.noreply.github.com>

Author: Copilot

.github/workflows/linter.md

@@ -29,6 +29,7 @@ Executes:
 - [Super-Linter](https://github.com/super-linter/super-linter), with some opinionated defaults.
 - [CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) to analyze the code.
 - [Ratchet](https://github.com/sethvargo/ratchet) to check that GitHub Action versions are pinned.
+- [Actions Permissions](https://github.com/GitHubSecurityLab/actions-permissions) to analyze and optimize workflow permissions.
 
 ### Permissions
 

.github/workflows/linter.yml

@@ -4,6 +4,7 @@
 # - [Super-Linter](https://github.com/super-linter/super-linter), with some opinionated defaults.
 # - [CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) to analyze the code.
 # - [Ratchet](https://github.com/sethvargo/ratchet) to check that GitHub Action versions are pinned.
+# - [Actions Permissions](https://github.com/GitHubSecurityLab/actions-permissions) to analyze and optimize workflow permissions.
 
 name: "Linter"
 on:
@@ -216,3 +217,85 @@ jobs:
         if: ${{ steps.get-files-to-lint.outputs.files }}
         with:
           args: "lint --format human --format actions ${{ steps.get-files-to-lint.outputs.files }}"
+
+  permissions-analysis:
+    name: 🔐 Workflow Permissions Analysis
+    runs-on: ${{ fromJson(inputs.runs-on) }}
+    if: ${{ inputs.action-files }}
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: "${{ inputs.lint-all && 1 || 0 }}"
+
+      - id: changed-files
+        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47.0.0
+        if: ${{ inputs.lint-all == false }}
+        with:
+          files: ${{ inputs.action-files }}
+          dir_names_exclude_current_dir: true
+
+      - id: get-files-to-analyze
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            const fs = require("node:fs");
+            const path = require("node:path");
+
+            const changedFiles = ${{ toJSON(steps.changed-files.outputs.all_changed_and_modified_files) }};
+
+            let actionFiles = [];
+            if (changedFiles !== null) {
+              actionFiles = changedFiles.split(" ").filter(file => file && fs.existsSync(file));
+            } else {
+              const actionFilesInput = ${{ toJson(inputs.action-files) }};
+
+              for (const actionFile of actionFilesInput.split("\n")) {
+                let sanitizedActionFile = actionFile.trim();
+                if (sanitizedActionFile === "") {
+                  continue;
+                }
+
+                if (path.isAbsolute(sanitizedActionFile)) {
+                  // Ensure actionFile is within the workspace
+                  if (!sanitizedActionFile.startsWith(process.env.GITHUB_WORKSPACE)) {
+                    return core.setFailed(`Action file / directory is not within the workspace: ${sanitizedActionFile}`);
+                  }
+                } else {
+                  sanitizedActionFile = path.join(process.env.GITHUB_WORKSPACE, sanitizedActionFile);
+                }
+                actionFiles.push(sanitizedActionFile);
+              }
+
+              if (actionFiles.length === 0) {
+                return core.setFailed("No action files to analyze.");
+              }
+
+              async function getActionFiles(actionFile) {
+                const globber = await glob.create(actionFile,{ matchactionFilesInput: false });
+                return await globber.glob();
+              }
+
+              actionFiles = (await Promise.all(actionFiles.map(getActionFiles)))
+                .flat()
+                .map((file) => path.relative(process.env.GITHUB_WORKSPACE, file));
+
+              if (actionFiles.length === 0) {
+                return core.setFailed("No action files to analyze.");
+              }
+            }
+
+            const files = actionFiles.map((file) => path.relative(process.env.GITHUB_WORKSPACE, file));
+            const filesOutput = [...new Set(files)].join("\n").trim();
+
+            if (filesOutput.length === 0) {
+              return;
+            }
+
+            core.setOutput("files", filesOutput);
+
+      - uses: GitHubSecurityLab/actions-permissions@f24e0c210427f4c43e516265a4ca94e1e30e95f9 # v1.0.10
+        if: ${{ steps.get-files-to-analyze.outputs.files }}
+        with:
+          path: ${{ steps.get-files-to-analyze.outputs.files }}