Skip to content

Commit 4d0cf68

Browse files
JacobPEvans-personalJacobPEvans-personal
committed
Merge main into renovate/main-actions-setup-go-6.x
2 parents fb95cdd + 326c27b commit 4d0cf68

15 files changed

Lines changed: 1808 additions & 130 deletions

‎.github/workflows/validate-plugin.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ jobs:
1515

1616
steps:
1717
- name: Checkout code
18-
uses: actions/checkout@v4
18+
uses: actions/checkout@v6
1919

2020
- name: Setup Go
2121
uses: actions/setup-go@v6
2222
with:
23-
go-version: '1.21'
23+
go-version: '1.25'
2424

2525
- name: Install cclint
2626
run: |

‎.markdownlint.json‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
{
22
"MD013": {
3-
"line_length": 160
4-
}
3+
"line_length": 160,
4+
"heading_line_length": 120,
5+
"code_block_line_length": 160,
6+
"tables": false
7+
},
8+
"MD060": false
59
}

‎codeql-resolver/.claude-plugin/plugin.json‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{
2+
"name": "codeql-resolver",
3+
"version": "1.0.0",
4+
"description": "Systematic CodeQL alert analysis and resolution for GitHub Actions workflows",
5+
"author": "Jacob Evans",
6+
"license": "MIT",
7+
"repository": "https://github.com/JacobPEvans/claude-code-plugins",
8+
"bugs": "https://github.com/JacobPEvans/claude-code-plugins/issues",
9+
"keywords": [
10+
"codeql",
11+
"security",
12+
"github-actions",
13+
"workflow",
14+
"permissions"
15+
],
16+
"commands": [
17+
{
18+
"name": "resolve-codeql",
19+
"description": "Analyze and resolve CodeQL alerts systematically",
20+
"category": "security"
21+
}
22+
],
23+
"agents": [
24+
{
25+
"name": "codeql-permissions-auditor",
26+
"description": "Fix workflow permission issues"
27+
},
28+
{
29+
"name": "codeql-expression-injector",
30+
"description": "Mitigate expression injection vulnerabilities"
31+
},
32+
{
33+
"name": "codeql-generic-resolver",
34+
"description": "Handle non-standard CodeQL alerts"
35+
}
36+
],
37+
"skills": [
38+
{
39+
"name": "codeql-permission-classification",
40+
"description": "Permission requirements for GitHub Actions"
41+
},
42+
{
43+
"name": "github-workflow-security-patterns",
44+
"description": "Canonical security patterns for GitHub workflows"
45+
}
46+
]
47+
}

‎codeql-resolver/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Jacob Evans
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎codeql-resolver/README.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# CodeQL Resolver
2+
3+
A Claude Code plugin that provides systematic analysis and resolution of CodeQL alerts in GitHub Actions workflows.
4+
5+
## Overview
6+
7+
**CodeQL Resolver** implements a three-tier command→agent→skill architecture for managing GitHub security scanning alerts:
8+
9+
- **`/resolve-codeql`** - Main command for discovering, classifying, and delegating CodeQL alerts
10+
- **3 Specialized Agents** - Permission auditor, expression injection fixer, generic resolver
11+
- **2 Reusable Skills** - Permission classification, security patterns
12+
13+
## Key Features
14+
15+
### Alert Classification
16+
Automatically categorizes CodeQL alerts by type:
17+
- ✅ **Permissions** - "Workflow does not contain permissions"
18+
- ✅ **Expression Injection** - Untrusted input in shell commands
19+
- ✅ **Other** - Resource leaks, hardcoded credentials, etc.
20+
21+
### Specialized Agents
22+
23+
#### 1. Permissions Auditor
24+
Fixes "Workflow does not contain permissions" alerts by:
25+
- Analyzing reusable workflow call requirements
26+
- Determining minimum permissions needed
27+
- Adding explicit least-privilege blocks
28+
29+
**Test case**: [ci-gate.yml](https://github.com/JacobPEvans/ai-assistant-instructions/blob/main/.github/workflows/ci-gate.yml) - Fixed 8 alerts with this agent's methodology
30+
31+
#### 2. Expression Injection Fixer
32+
Mitigates GitHub Actions expression injection vulnerabilities by:
33+
- Identifying dangerous untrusted inputs
34+
- Wrapping in environment variables
35+
- Following GitHub's official security guidance
36+
37+
#### 3. Generic Resolver
38+
Handles other CodeQL alert types:
39+
- Resource leaks, hardcoded credentials, unsafe shell
40+
- Escalates unclear issues for human review
41+
- Provides detailed analysis when patterns match
42+
43+
## Installation
44+
45+
### Option 1: Add via Marketplace (Recommended)
46+
47+
```bash
48+
/plugin marketplace add /path/to/claude-code-plugins
49+
/plugin install codeql-resolver@jacobpevans-plugins
50+
```
51+
52+
### Option 2: Local Development
53+
54+
```bash
55+
claude --plugin-dir /path/to/codeql-resolver
56+
```
57+
58+
## Usage
59+
60+
### List All Alerts
61+
62+
```bash
63+
/resolve-codeql
64+
```
65+
66+
### Fix All Alerts
67+
68+
```bash
69+
/resolve-codeql fix
70+
```
71+
72+
### Fix Specific Alert Type
73+
74+
```bash
75+
/resolve-codeql type:permissions # Fix only permissions alerts
76+
/resolve-codeql type:injection # Fix only expression injection
77+
/resolve-codeql type:other # Fix other alert types
78+
```
79+
80+
### Fix Specific File
81+
82+
```bash
83+
/resolve-codeql file:.github/workflows/ci-gate.yml
84+
```
85+
86+
## Architecture
87+
88+
```
89+
┌────────────────────────────────────┐
90+
│ /resolve-codeql (Command) │
91+
│ - Discover alerts via GitHub API │
92+
│ - Classify by type │
93+
│ - Delegate to specialists │
94+
│ - Verify fixes │
95+
└────────────────┬───────────────────┘
96+
│
97+
┌───────┼───────┐
98+
│ │ │
99+
▼ ▼ ▼
100+
┌────────┬────────┬──────────┐
101+
│Perms │Inject │Generic │
102+
│Auditor │Fixer │Resolver │
103+
└────────┴────────┴──────────┘
104+
│ │ │
105+
└───────┼───────┘
106+
│
107+
Skills
108+
┌──────────────────┐
109+
│ Permission │
110+
│ Classification │
111+
│ │
112+
│ Workflow │
113+
│ Security Patterns│
114+
└──────────────────┘
115+
```
116+
117+
## Plugin Structure
118+
119+
```
120+
codeql-resolver/
121+
├── .claude-plugin/
122+
│ └── plugin.json # Plugin manifest
123+
├── hooks/
124+
│ └── hooks.json # Hook configuration
125+
├── agents/
126+
│ ├── codeql-permissions-auditor.md
127+
│ ├── codeql-expression-injector.md
128+
│ └── codeql-generic-resolver.md
129+
├── skills/
130+
│ ├── codeql-permission-classification.md
131+
│ └── github-workflow-security-patterns.md
132+
├── commands/
133+
│ └── resolve-codeql.md
134+
└── README.md
135+
```
136+
137+
## Examples
138+
139+
### Example 1: Fix ci-gate.yml Permissions
140+
141+
```bash
142+
cd ~/git/ai-assistant-instructions
143+
/resolve-codeql file:.github/workflows/ci-gate.yml
144+
```
145+
146+
**Output**:
147+
```
148+
CodeQL Alert Resolution Report
149+
===============================
150+
File: .github/workflows/ci-gate.yml
151+
Alerts found: 8 (permissions)
152+
153+
Fixing permissions on reusable workflow calls...
154+
✓ cclint (line 103) - Added contents:read
155+
✓ validate-cclint (line 109) - Added contents:read, pull-requests:write
156+
✓ markdownlint (line 118) - Added contents:read
157+
✓ spellcheck (line 124) - Added contents:read
158+
✓ token-limits (line 130) - Added contents:read, pull-requests:write
159+
✓ validate-instructions (line 146) - Added contents:read
160+
✓ yaml-lint (line 152) - Added contents:read
161+
✓ gate (line 160) - Added permissions:{}
162+
163+
Verification: Running CodeQL scan...
164+
✓ All 8 alerts resolved!
165+
166+
Commit: "security: fix CodeQL alerts - add explicit permissions"
167+
```
168+
169+
### Example 2: Fix Expression Injection
170+
171+
```bash
172+
/resolve-codeql type:injection
173+
```
174+
175+
**Output**:
176+
```
177+
CodeQL Alert Resolution Report
178+
===============================
179+
Alert Type: Expression Injection
180+
181+
Analyzing vulnerable patterns...
182+
Found 1 alert in .github/workflows/deploy.yml:45
183+
184+
Fixing expression injection...
185+
✓ Added env: block for PR_BODY variable
186+
✓ Updated script to use $PR_BODY instead of untrusted expression
187+
188+
Verification: ✓ Alert resolved!
189+
190+
Commit: "security: fix CodeQL - mitigate expression injection"
191+
```
192+
193+
## Real-World Test Case
194+
195+
The plugin was designed with [PR #413](https://github.com/JacobPEvans/ai-assistant-instructions/pull/413) as a real test case:
196+
197+
- **Starting point**: 8 CodeQL alerts in ci-gate.yml
198+
- **Issue**: Missing `permissions:` blocks on reusable workflow calls
199+
- **Solution**: Permissions auditor agent analyzed each job and added appropriate blocks
200+
- **Result**: All 8 alerts resolved with single commit
201+
202+
## Security Principles
203+
204+
All fixes follow these security principles:
205+
206+
1. **Least Privilege** - Requests only minimum permissions needed
207+
2. **Explicit Over Implicit** - Declares permissions explicitly rather than relying on defaults
208+
3. **Auditable** - All changes follow documented patterns and are reviewable
209+
4. **Safe By Default** - Expression injection vulnerabilities wrapped in env vars
210+
5. **Escalation** - Unclear issues flagged for human review, not auto-fixed
211+
212+
## References
213+
214+
- [GitHub Security Blog: Catching GitHub Actions Workflow Injections](https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/)
215+
- [GitHub Actions Security: Best Practices](https://docs.github.com/en/actions/security-guides)
216+
- [CodeQL Rules Documentation](https://docs.github.com/en/code-security/codeql)
217+
218+
## Development
219+
220+
### Local Testing
221+
222+
```bash
223+
cd ~/git/claude-code-plugins/feat/codeql-resolver/codeql-resolver
224+
python3 scripts/test_codeql_plugin.py
225+
```
226+
227+
### Adding New Alert Types
228+
229+
1. Create new agent in `agents/codeql-{type}-resolver.md`
230+
2. Add to `plugin.json` agents list
231+
3. Update `/resolve-codeql` command to delegate to new agent
232+
4. Create corresponding skill if pattern is reusable
233+
5. Add tests in `scripts/test_codeql_plugin.py`
234+
235+
## Contributing
236+
237+
See [CONTRIBUTING.md](../docs/CONTRIBUTING.md)
238+
239+
## License
240+
241+
Apache 2.0

0 commit comments

Comments
 (0)