|
| 1 | +# CodeQL Security Analysis |
| 2 | + |
| 3 | +This repository uses CodeQL for automated security scanning of C/C++ source code. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The CodeQL workflow (`codeql.yml`) performs static analysis security testing (SAST) on: |
| 8 | + |
| 9 | +- **C Code**: Core CPU detection in `src/` |
| 10 | +- **C Code**: SIMD implementations in `features/` |
| 11 | +- **C/C++ Headers**: Public API in `include/` |
| 12 | +- **C++ Code**: C++ compatibility tests in `tests/` |
| 13 | + |
| 14 | +## Workflow Triggers |
| 15 | + |
| 16 | +The CodeQL analysis runs automatically on: |
| 17 | + |
| 18 | +1. **Push events** to `main` branch |
| 19 | +2. **Pull requests** targeting `main` branch |
| 20 | +3. **Scheduled runs** every Monday at 2:30 AM UTC |
| 21 | +4. **Manual dispatch** via GitHub Actions UI |
| 22 | + |
| 23 | +## What Gets Analyzed |
| 24 | + |
| 25 | +### C/C++ Analysis |
| 26 | + |
| 27 | +- Core CPU detection (`src/dynemit.c`) |
| 28 | +- SIMD feature implementations (`features/*/`) |
| 29 | +- Public headers (`include/dynemit/`) |
| 30 | +- ifunc resolvers and runtime dispatch |
| 31 | +- Checks for: |
| 32 | + - Buffer overflows |
| 33 | + - Integer overflows |
| 34 | + - Out-of-bounds array access |
| 35 | + - NULL pointer dereferences |
| 36 | + - Unsafe pointer arithmetic |
| 37 | + - Memory alignment issues |
| 38 | + - Use-after-free |
| 39 | + - Double-free |
| 40 | + - Memory leaks |
| 41 | + |
| 42 | +## Query Suites |
| 43 | + |
| 44 | +The workflow uses enhanced query suites: |
| 45 | + |
| 46 | +- `security-extended`: Extended set of security queries |
| 47 | +- `security-and-quality`: Security queries plus code quality checks |
| 48 | + |
| 49 | +## Build Process |
| 50 | + |
| 51 | +### C/C++ Build |
| 52 | + |
| 53 | +The C/C++ code is built using CMake: |
| 54 | + |
| 55 | +```bash |
| 56 | +cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13 |
| 57 | +cmake --build build -j$(nproc) |
| 58 | +``` |
| 59 | + |
| 60 | +This ensures CodeQL can analyze the complete codebase including all SIMD implementations. |
| 61 | + |
| 62 | +## Viewing Results |
| 63 | + |
| 64 | +### Pull Requests |
| 65 | + |
| 66 | +- CodeQL findings appear as annotations directly in PRs |
| 67 | +- New issues are highlighted in the diff view |
| 68 | +- Security issues block PR merging until resolved |
| 69 | + |
| 70 | +### Security Tab |
| 71 | + |
| 72 | +- Navigate to **Security** > **Code scanning alerts** in the repository |
| 73 | +- Filter by language, severity, or rule |
| 74 | +- View detailed analysis and remediation suggestions |
| 75 | + |
| 76 | +## Configuration |
| 77 | + |
| 78 | +The analysis is configured in: |
| 79 | + |
| 80 | +- `.github/workflows/codeql.yml` - Main workflow |
| 81 | +- `.github/workflows/codeql/codeql-config.yml` - Path configuration and query suites |
| 82 | + |
| 83 | +### Paths Analyzed |
| 84 | + |
| 85 | +The configuration analyzes these paths: |
| 86 | + |
| 87 | +```yaml |
| 88 | +paths: |
| 89 | + - src |
| 90 | + - features |
| 91 | + - include |
| 92 | +``` |
| 93 | +
|
| 94 | +### Paths Excluded |
| 95 | +
|
| 96 | +The following paths are excluded from analysis: |
| 97 | +
|
| 98 | +```yaml |
| 99 | +paths-ignore: |
| 100 | + - tests |
| 101 | + - bench |
| 102 | + - build |
| 103 | + - docs |
| 104 | + - scripts |
| 105 | + - '**/*.md' |
| 106 | +``` |
| 107 | +
|
| 108 | +## Best Practices |
| 109 | +
|
| 110 | +1. **Review findings promptly**: Address security issues as soon as they appear |
| 111 | +2. **Don't dismiss without investigation**: Understand each finding before closing |
| 112 | +3. **Monitor scheduled scans**: Weekly scans catch newly discovered vulnerability patterns |
| 113 | +4. **Test with sanitizers**: Use AddressSanitizer and UndefinedBehaviorSanitizer locally |
| 114 | +5. **Follow secure coding**: Validate inputs, check bounds, handle NULL pointers |
| 115 | +
|
| 116 | +## Common Security Issues in SIMD Code |
| 117 | +
|
| 118 | +### Buffer Overflows |
| 119 | +
|
| 120 | +SIMD code processes multiple elements at once. Ensure loop bounds are correct: |
| 121 | +
|
| 122 | +```c |
| 123 | +// Potential issue |
| 124 | +for (size_t i = 0; i < n; i += 8) { |
| 125 | + // May read past array bounds if n is not multiple of 8 |
| 126 | +} |
| 127 | + |
| 128 | +// Better |
| 129 | +size_t i = 0; |
| 130 | +for (; i + 8 <= n; i += 8) { |
| 131 | + // Process 8 elements |
| 132 | +} |
| 133 | +for (; i < n; i++) { |
| 134 | + // Handle remainder |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +### Integer Overflows |
| 139 | + |
| 140 | +Size calculations can overflow: |
| 141 | + |
| 142 | +```c |
| 143 | +// Potential issue |
| 144 | +size_t total = n * sizeof(float); // May overflow |
| 145 | + |
| 146 | +// Better |
| 147 | +if (n > SIZE_MAX / sizeof(float)) { |
| 148 | + // Handle error |
| 149 | +} |
| 150 | +size_t total = n * sizeof(float); |
| 151 | +``` |
| 152 | + |
| 153 | +### Memory Alignment |
| 154 | + |
| 155 | +SIMD operations require aligned memory: |
| 156 | + |
| 157 | +```c |
| 158 | +// Potential issue |
| 159 | +float *data = malloc(n * sizeof(float)); // May not be aligned |
| 160 | + |
| 161 | +// Better |
| 162 | +float *data = aligned_alloc(32, n * sizeof(float)); // 32-byte aligned for AVX |
| 163 | +``` |
| 164 | + |
| 165 | +## Resources |
| 166 | + |
| 167 | +- [CodeQL Documentation](https://codeql.github.com/docs/) |
| 168 | +- [CodeQL for C/C++](https://codeql.github.com/docs/codeql-language-guides/codeql-for-cpp/) |
| 169 | +- [GitHub Code Scanning](https://docs.github.com/en/code-security/code-scanning) |
| 170 | +- [C/C++ Security Queries](https://codeql.github.com/codeql-query-help/cpp/) |
| 171 | + |
| 172 | +## Support |
| 173 | + |
| 174 | +For issues with CodeQL analysis: |
| 175 | + |
| 176 | +1. Check the [Actions logs](https://github.com/MuriloChianfa/libdynemit/actions) |
| 177 | +2. Review [Security tab](https://github.com/MuriloChianfa/libdynemit/security) |
| 178 | +3. Open an issue with the `security` label |
| 179 | +4. Contact repository maintainers |
| 180 | + |
| 181 | +## False Positives |
| 182 | + |
| 183 | +If CodeQL reports a false positive: |
| 184 | + |
| 185 | +1. Verify it's actually a false positive |
| 186 | +2. Add an inline comment explaining why it's safe |
| 187 | +3. Use `// lgtm[cpp/rule-id]` to suppress specific warnings |
| 188 | +4. Document the suppression reason |
| 189 | + |
| 190 | +Example: |
| 191 | + |
| 192 | +```c |
| 193 | +// This is safe because n is validated to be <= MAX_SIZE before this point |
| 194 | +// lgtm[cpp/integer-multiplication-cast-to-long] |
| 195 | +size_t total = n * sizeof(float); |
| 196 | +``` |
| 197 | + |
| 198 | +## Security Disclosure |
| 199 | + |
| 200 | +If CodeQL identifies a security vulnerability: |
| 201 | + |
| 202 | +- **DO NOT** discuss it in public issues |
| 203 | +- Report via email: murilo.chianfa@outlook.com |
| 204 | +- See [SECURITY.md](SECURITY.md) for full disclosure process |
0 commit comments