Skip to content

Commit 5b67da8

Browse files
gfsgfs
committed
Check in extractor ptototype, tools, test queries
1 parent 2a0a312 commit 5b67da8

22 files changed

Lines changed: 1190 additions & 0 deletions

‎csharp-il/README.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# C# IL Extractor for CodeQL
2+
3+
A CodeQL extractor that analyzes compiled .NET assemblies (DLL/EXE files) at the IL (Intermediate Language) level.
4+
5+
## Overview
6+
7+
This extractor enables CodeQL analysis of compiled C# code without requiring source code. It directly extracts IL instructions from .NET assemblies and creates a queryable database for control flow and call graph analysis.
8+
9+
## Features
10+
11+
- ✅ Extract from any .NET DLL/EXE file
12+
- ✅ Capture complete IL instruction streams
13+
- ✅ Track control flow (branches, loops)
14+
- ✅ Build call graphs across assemblies
15+
- ✅ Analyze exception handlers (try/catch/finally)
16+
- ✅ Support for cross-assembly flow tracing
17+
18+
## Quick Start
19+
20+
### Prerequisites
21+
22+
- .NET 8.0 SDK or later
23+
- Mono.Cecil library (automatically restored via NuGet)
24+
25+
### Build the Extractor
26+
27+
```bash
28+
cd csharp-il
29+
dotnet build extractor/Semmle.Extraction.CSharp.IL
30+
```
31+
32+
### Extract a DLL
33+
34+
```bash
35+
dotnet run --project extractor/Semmle.Extraction.CSharp.IL -- \
36+
path/to/your/assembly.dll \
37+
output.trap
38+
```
39+
40+
### Try the Test Example
41+
42+
```bash
43+
# Extract the test assembly
44+
dotnet run --project extractor/Semmle.Extraction.CSharp.IL -- \
45+
test-inputs/TestAssembly/bin/Debug/net8.0/TestAssembly.dll \
46+
test-inputs/TestAssembly.trap
47+
48+
# View the results
49+
head -100 test-inputs/TestAssembly.trap
50+
```
51+
52+
## What Gets Extracted
53+
54+
The extractor captures:
55+
56+
1. **Assemblies**: Name, version, file location
57+
2. **Types**: Classes, structs, interfaces, enums
58+
3. **Methods**: Signatures, parameters, return types
59+
4. **IL Instructions**: Opcodes, operands, offsets
60+
5. **Control Flow**: Branch targets, fall-through paths
61+
6. **Call Graph**: Method calls with qualified names
62+
7. **Exception Handlers**: Try/catch/finally blocks
63+
64+
## Database Schema
65+
66+
The extractor creates a CodeQL database with the following structure:
67+
68+
```
69+
assemblies(id, file, name, version)
70+
types(id, full_name, namespace, name)
71+
methods(id, name, signature, type_id)
72+
il_instructions(id, opcode_num, opcode_name, offset, method)
73+
il_branch_target(instruction, target_offset)
74+
il_call_target_unresolved(instruction, target_method_name)
75+
...
76+
```
77+
78+
See `documentation/dbscheme-guide.md` for complete schema documentation.
79+
80+
## Use Cases
81+
82+
### Security Analysis
83+
- Trace data flow through compiled libraries
84+
- Find paths to sensitive API calls
85+
- Analyze third-party dependencies
86+
87+
### Code Understanding
88+
- Build call graphs from compiled code
89+
- Understand control flow in obfuscated assemblies
90+
- Analyze library usage patterns
91+
92+
### Cross-Assembly Analysis
93+
- Trace execution across multiple DLLs
94+
- Find inter-assembly dependencies
95+
- Analyze full application stacks
96+
97+
## Project Status
98+
99+
**Current Phase**: Schema Complete ✅
100+
101+
- ✅ Phase 0: POC with Mono.Cecil
102+
- ✅ Phase 1: TRAP File Extractor
103+
- ✅ Phase 2: Database Schema
104+
- ⬜ Phase 3: QL Library (In Progress)
105+
- ⬜ Phase 4: Call Graph Predicates
106+
- ⬜ Phase 5: Basic Blocks
107+
- ⬜ Phase 6: End-to-End Testing
108+
109+
See `wipStatus/CURRENT-STATUS.md` for detailed progress.
110+
111+
## Directory Structure
112+
113+
```
114+
csharp-il/
115+
├── extractor/ # IL extraction tool
116+
│ └── Semmle.Extraction.CSharp.IL/
117+
├── ql/ # QL library (coming soon)
118+
│ └── lib/
119+
│ └── semmlecode.csharp.il.dbscheme
120+
├── test-inputs/ # Test assemblies
121+
│ └── TestAssembly/
122+
├── documentation/ # Documentation
123+
│ └── dbscheme-guide.md
124+
└── wipStatus/ # Development notes
125+
├── CURRENT-STATUS.md
126+
├── PLAN.md
127+
└── ...
128+
```
129+
130+
## Example: Extracting TestAssembly
131+
132+
The `test-inputs/TestAssembly` project contains example C# code with:
133+
- If/else statements
134+
- Method calls
135+
- Loops
136+
- Arithmetic operations
137+
138+
After extraction, you can see the IL representation:
139+
140+
```trap
141+
types(3, "TestNamespace.SimpleClass", "TestNamespace", "SimpleClass")
142+
methods(4, "SimpleMethod", "Void SimpleMethod()", 3)
143+
il_instructions(13, 43, "brfalse.s", 9, 4)
144+
il_branch_target(13, 26)
145+
il_instructions(16, 39, "call", 17, 4)
146+
il_call_target_unresolved(16, "System.Console.WriteLine")
147+
```
148+
149+
## Design Philosophy
150+
151+
### Simple Extraction, Smart Queries
152+
153+
The extractor follows CodeQL best practices:
154+
155+
- **Extractor**: Simple and fast - just write IL facts to TRAP files
156+
- **QL Library**: Smart analysis - compute CFG, reachability, etc. at query time
157+
158+
This architecture keeps extraction fast while enabling sophisticated analysis.
159+
160+
### Why IL Instead of Decompilation?
161+
162+
1. **Accurate**: IL is the ground truth, no decompiler errors
163+
2. **Fast**: No expensive decompilation step
164+
3. **Reliable**: Works on all .NET code, even obfuscated
165+
4. **Complete**: Exact control flow and calling conventions
166+
167+
## Documentation
168+
169+
- `documentation/dbscheme-guide.md` - Complete schema reference
170+
- `wipStatus/PLAN.md` - Project plan and approach
171+
- `wipStatus/IMPLEMENTATION.md` - Implementation roadmap
172+
- `wipStatus/CURRENT-STATUS.md` - Current progress
173+
174+
## Contributing
175+
176+
This is an experimental extractor under active development. Contributions welcome!
177+
178+
Current focus areas:
179+
- QL library implementation
180+
- Basic block computation
181+
- Call graph predicates
182+
- Test query development
183+
184+
## Technical Details
185+
186+
### Technologies Used
187+
188+
- **Language**: C# (.NET 8.0)
189+
- **IL Parser**: Mono.Cecil
190+
- **Target**: .NET Standard 2.0+ assemblies
191+
- **Output Format**: CodeQL TRAP files
192+
193+
### Limitations
194+
195+
Currently extracts compiled IL only:
196+
- ✅ Class and method names
197+
- ✅ Control flow (branches, calls)
198+
- ✅ Method signatures
199+
- ❌ Local variable names (without PDB files)
200+
- ❌ Source locations (without PDB files)
201+
202+
These are sufficient for control flow and call graph analysis!
203+
204+
## License
205+
206+
Part of the CodeQL project. See LICENSE in repository root.
207+
208+
## Contact
209+
210+
For questions about this extractor, see the wipStatus documents or create an issue.
211+
212+
---
213+
214+
**Quick Links**:
215+
- [Current Status](wipStatus/CURRENT-STATUS.md)
216+
- [Schema Guide](documentation/dbscheme-guide.md)
217+
- [Implementation Plan](wipStatus/IMPLEMENTATION.md)

‎csharp-il/codeql-extractor.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: "csharpil"
2+
aliases:
3+
- "cil"
4+
- "csharp-il"
5+
display_name: "C# IL"
6+
version: 0.0.1
7+
column_kind: "utf16"
8+
build_modes:
9+
- autobuild
10+
- manual
11+
- none
12+
file_types:
13+
- name: cil
14+
display_name: C# IL sources
15+
extensions:
16+
- .dll
17+
- .exe

0 commit comments

Comments
 (0)