Skip to content

Commit 943c34f

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
Claude/integrate security tools h nyd u (#6)
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 58c5eed commit 943c34f

5 files changed

Lines changed: 542 additions & 1 deletion

File tree

‎COMPATIBILITY.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# php-aegis Compatibility Strategy
2+
3+
## The Problem
4+
5+
php-aegis requires PHP 8.1+, but WordPress officially supports PHP 7.4+. This limits adoption in the WordPress ecosystem where many hosts still run PHP 7.4 or 8.0.
6+
7+
## Strategy: Dual-Package Approach
8+
9+
Instead of downgrading the main library, we provide a separate compatibility package.
10+
11+
```
12+
hyperpolymath/php-aegis # PHP 8.1+ (main, recommended)
13+
hyperpolymath/php-aegis-compat # PHP 7.4+ (polyfill, limited)
14+
```
15+
16+
### Why Not Downgrade?
17+
18+
1. **Security**: PHP 8.1+ has better security defaults
19+
2. **Type Safety**: Union types, enums, readonly properties
20+
3. **Performance**: PHP 8.x is significantly faster
21+
4. **Maintenance**: Supporting old PHP versions increases complexity
22+
23+
### The Compatibility Package
24+
25+
`php-aegis-compat` provides:
26+
- Same API surface as php-aegis
27+
- Works on PHP 7.4, 8.0
28+
- Gracefully degrades when php-aegis is available
29+
30+
```php
31+
<?php
32+
// php-aegis-compat automatically uses php-aegis if available
33+
34+
namespace PhpAegisCompat;
35+
36+
if (class_exists('\\PhpAegis\\Sanitizer')) {
37+
// PHP 8.1+ with php-aegis installed
38+
class_alias('\\PhpAegis\\Sanitizer', 'PhpAegisCompat\\Sanitizer');
39+
} else {
40+
// PHP 7.4/8.0 fallback
41+
class Sanitizer {
42+
public static function html(string $input): string {
43+
return htmlspecialchars($input, ENT_QUOTES | ENT_HTML5, 'UTF-8');
44+
}
45+
// ... limited subset of methods
46+
}
47+
}
48+
```
49+
50+
### Installation
51+
52+
```bash
53+
# For PHP 8.1+ projects (recommended)
54+
composer require hyperpolymath/php-aegis
55+
56+
# For PHP 7.4+ projects (compatibility)
57+
composer require hyperpolymath/php-aegis-compat
58+
```
59+
60+
### What's Included in Compat
61+
62+
| Feature | php-aegis | php-aegis-compat |
63+
|---------|-----------|------------------|
64+
| `Sanitizer::html()` | ✅ | ✅ |
65+
| `Sanitizer::attr()` | ✅ | ✅ |
66+
| `Sanitizer::js()` | ✅ | ✅ |
67+
| `Sanitizer::url()` | ✅ | ✅ |
68+
| `Validator::email()` | ✅ | ✅ |
69+
| `Validator::url()` | ✅ | ✅ |
70+
| `Validator::ip()` | ✅ | ✅ |
71+
| `Headers::secure()` | ✅ | ✅ |
72+
| `TurtleEscaper` | ✅ | ❌ (complex escaping) |
73+
| Enums/Union types | ✅ | ❌ (PHP 8.1+) |
74+
| `readonly` properties | ✅ | ❌ (PHP 8.1+) |
75+
76+
---
77+
78+
## WordPress Adapter
79+
80+
WordPress uses `snake_case` naming conventions. We provide a WordPress adapter.
81+
82+
### Option 1: Function Wrappers
83+
84+
```php
85+
<?php
86+
// wp-content/mu-plugins/php-aegis-wordpress.php
87+
88+
if (!class_exists('\\PhpAegis\\Sanitizer') && !class_exists('\\PhpAegisCompat\\Sanitizer')) {
89+
return; // Neither package installed
90+
}
91+
92+
$sanitizer = class_exists('\\PhpAegis\\Sanitizer')
93+
? '\\PhpAegis\\Sanitizer'
94+
: '\\PhpAegisCompat\\Sanitizer';
95+
96+
// WordPress-style function wrappers
97+
function aegis_html(string $input): string {
98+
global $sanitizer;
99+
return $sanitizer::html($input);
100+
}
101+
102+
function aegis_attr(string $input): string {
103+
global $sanitizer;
104+
return $sanitizer::attr($input);
105+
}
106+
107+
function aegis_js(string $input): string {
108+
global $sanitizer;
109+
return $sanitizer::js($input);
110+
}
111+
112+
function aegis_url(string $input): string {
113+
global $sanitizer;
114+
return $sanitizer::url($input);
115+
}
116+
117+
// Headers
118+
function aegis_send_security_headers(): void {
119+
if (class_exists('\\PhpAegis\\Headers')) {
120+
\PhpAegis\Headers::secure();
121+
} elseif (class_exists('\\PhpAegisCompat\\Headers')) {
122+
\PhpAegisCompat\Headers::secure();
123+
}
124+
}
125+
```
126+
127+
### Option 2: WordPress Plugin
128+
129+
A dedicated WordPress plugin that:
130+
1. Auto-detects php-aegis or php-aegis-compat
131+
2. Registers WordPress-style functions
132+
3. Integrates with WordPress's existing escaping functions
133+
4. Adds admin UI for security header configuration
134+
135+
---
136+
137+
## Laravel Adapter
138+
139+
Laravel uses dependency injection. We provide a service provider.
140+
141+
```php
142+
<?php
143+
// config/app.php
144+
'providers' => [
145+
PhpAegis\Laravel\AegisServiceProvider::class,
146+
],
147+
148+
// Usage in controllers
149+
public function store(Request $request, Sanitizer $sanitizer)
150+
{
151+
$safe = $sanitizer->html($request->input('content'));
152+
}
153+
154+
// Blade directive
155+
@aegis($userContent) // Calls Sanitizer::html()
156+
```
157+
158+
---
159+
160+
## Migration Path
161+
162+
### For WordPress Themes/Plugins
163+
164+
```php
165+
// Before: Using WordPress functions only
166+
echo esc_html($user_input);
167+
168+
// After: Using php-aegis with WordPress fallback
169+
if (function_exists('aegis_html')) {
170+
echo aegis_html($user_input);
171+
} else {
172+
echo esc_html($user_input);
173+
}
174+
175+
// Or: Graceful one-liner
176+
echo function_exists('aegis_html') ? aegis_html($user_input) : esc_html($user_input);
177+
```
178+
179+
### For New Projects
180+
181+
```php
182+
// Just use php-aegis directly
183+
use PhpAegis\Sanitizer;
184+
185+
echo Sanitizer::html($user_input);
186+
```
187+
188+
---
189+
190+
## Version Support Timeline
191+
192+
| PHP Version | Support Status | Recommended Package |
193+
|-------------|---------------|---------------------|
194+
| 7.4 | Legacy (EOL Dec 2022) | php-aegis-compat |
195+
| 8.0 | Legacy (EOL Nov 2023) | php-aegis-compat |
196+
| 8.1 | Security fixes only | php-aegis |
197+
| 8.2 | Active | php-aegis |
198+
| 8.3 | Active (current) | php-aegis |
199+
| 8.4+ | Future | php-aegis |
200+
201+
**Recommendation**: Upgrade to PHP 8.2+ and use php-aegis directly.
202+
203+
---
204+
205+
## Implementation Checklist
206+
207+
- [ ] Create `hyperpolymath/php-aegis-compat` repository
208+
- [ ] Implement core Sanitizer/Validator classes for PHP 7.4
209+
- [ ] Add auto-detection for php-aegis (use if available)
210+
- [ ] Create WordPress mu-plugin adapter
211+
- [ ] Create Laravel service provider
212+
- [ ] Publish both packages to Packagist
213+
- [ ] Document migration paths
214+
215+
---
216+
217+
*This strategy maximizes adoption while maintaining security and code quality in the main package.*

‎HANDOVER_SANCTIFY.md‎

Lines changed: 149 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,17 +228,165 @@ RECOMMENDATION:
228228
|----------|-------|--------|
229229
| P0 | Pre-built binaries / Docker image | Medium |
230230
| P0 | PHP 8.x syntax support | High |
231+
| P0 | Official GitHub Action (`sanctify-php-action`) | Medium |
231232
| P1 | WordPress-specific rulesets | Medium |
232233
| P1 | RDF/Turtle context detection | Medium |
234+
| P1 | SARIF output for GitHub Security tab | Low |
235+
| P2 | Incremental analysis (cache, scan changed files only) | High |
233236
| P2 | IndieWeb protocol patterns | Low |
234237
| P2 | php-aegis fix suggestions in output | Low |
235238

239+
---
240+
241+
## Additional Findings (Report 2)
242+
243+
### 6. GitHub Action Required
244+
245+
**Problem**: No official GitHub Action for CI integration.
246+
247+
**Impact**: Teams must write custom workflow configuration or use Docker manually.
248+
249+
**Recommendation**: Create `hyperpolymath/sanctify-php-action` with:
250+
```yaml
251+
# .github/workflows/security.yml
252+
- uses: hyperpolymath/sanctify-php-action@v1
253+
with:
254+
path: ./src
255+
config: sanctify.yml
256+
sarif-output: results.sarif
257+
```
258+
259+
### 7. SARIF Output for GitHub Integration
260+
261+
**What Works Well**: SARIF format enables direct GitHub Security tab integration.
262+
263+
**Enhancement**: Ensure SARIF output includes:
264+
- Rule descriptions with OWASP references
265+
- Severity levels mapped to GitHub's critical/high/medium/low
266+
- Fix suggestions linking to php-aegis methods
267+
268+
```json
269+
{
270+
"runs": [{
271+
"tool": { "driver": { "name": "sanctify-php" } },
272+
"results": [{
273+
"ruleId": "xss-output",
274+
"level": "error",
275+
"message": { "text": "Unescaped output" },
276+
"fixes": [{
277+
"description": { "text": "Use PhpAegis\\Sanitizer::html()" }
278+
}]
279+
}]
280+
}]
281+
}
282+
```
283+
284+
### 8. Incremental Analysis
285+
286+
**Problem**: Full codebase scans are slow on large projects.
287+
288+
**Recommendation**:
289+
- Cache AST and taint analysis results
290+
- On subsequent runs, only analyze changed files
291+
- Invalidate cache when dependencies change
292+
- Use file modification timestamps or git diff
293+
294+
```bash
295+
# First run: full analysis, build cache
296+
sanctify analyze ./src --cache .sanctify-cache
297+
298+
# Subsequent runs: incremental
299+
sanctify analyze ./src --cache .sanctify-cache --incremental
300+
```
301+
302+
### 9. Composer Plugin Wrapper
303+
304+
**Problem**: PHP developers expect `composer require` installation.
305+
306+
**Recommendation**: Create a Composer plugin that:
307+
1. Downloads pre-built binary for platform
308+
2. Provides `vendor/bin/sanctify` wrapper
309+
3. Handles updates via Composer
310+
311+
```bash
312+
composer require --dev hyperpolymath/sanctify-php
313+
vendor/bin/sanctify analyze ./src
314+
```
315+
316+
---
317+
318+
## Standalone vs Combined Operation
319+
320+
### Minimal Requirements for Each Tool
321+
322+
**php-aegis standalone** (runtime protection):
323+
- Zero dependencies (works everywhere PHP runs)
324+
- Static methods for easy drop-in usage
325+
- Works without sanctify-php installed
326+
327+
**sanctify-php standalone** (static analysis):
328+
- Pre-built binary (no Haskell needed)
329+
- SARIF output for any CI system
330+
- Works without php-aegis (just reports issues)
331+
332+
### Combined Synergies
333+
334+
When both tools are used together:
335+
336+
```
337+
┌─────────────────────────────────────────────────────────────────┐
338+
│ Combined Workflow │
339+
├─────────────────────────────────────────────────────────────────┤
340+
│ │
341+
│ ┌────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
342+
│ │ Write │──▶│ sanctify-php │──▶│ Fix with │ │
343+
│ │ Code │ │ (finds issues) │ │ php-aegis │ │
344+
│ └────────────┘ └─────────────────┘ └──────────────────┘ │
345+
│ │ │ │
346+
│ ▼ ▼ │
347+
│ ┌─────────────────────────────────────┐ │
348+
│ │ sanctify-php recognizes php-aegis │ │
349+
│ │ methods as "safe sinks" in taint │ │
350+
│ │ analysis, reducing false positives │ │
351+
│ └─────────────────────────────────────┘ │
352+
│ │
353+
└─────────────────────────────────────────────────────────────────┘
354+
```
355+
356+
**Key synergy**: sanctify-php should recognize php-aegis sanitizers as safe:
357+
```haskell
358+
-- sanctify-php taint rules
359+
safeSinks = [
360+
"PhpAegis\\Sanitizer::html",
361+
"PhpAegis\\Sanitizer::attr",
362+
"PhpAegis\\Sanitizer::js",
363+
"PhpAegis\\Sanitizer::css",
364+
"PhpAegis\\Sanitizer::url",
365+
"PhpAegis\\TurtleEscaper::string",
366+
"PhpAegis\\TurtleEscaper::iri"
367+
]
368+
```
369+
370+
---
371+
372+
## Integration Metrics
373+
374+
| Metric | Before Integration | After Integration |
375+
|--------|-------------------|-------------------|
376+
| Files with `strict_types` | 0 | 24 (100%) |
377+
| PHP version | 7.4+ | 8.2+ |
378+
| WordPress version | 5.8+ | 6.4+ |
379+
| CI security checks | 0 | 4 |
380+
381+
---
382+
236383
## Contact
237384

238385
For questions about this integration or to coordinate between repos:
239386
- php-aegis: https://github.com/hyperpolymath/php-aegis
387+
- sanctify-php: https://github.com/hyperpolymath/sanctify-php
240388
- Integration tested in: wp-sinople-theme
241389

242390
---
243391

244-
*Generated from real-world WordPress semantic theme integration experience.*
392+
*Generated from real-world WordPress semantic theme integration experience (Reports 1 & 2).*

0 commit comments

Comments
 (0)