Update docs for 0.6: with()/ConfigLayer, companion OWASP, preset pages, trusted-bot wiring#6
Merged
Merged
Conversation
…s, trusted-bot wiring
There was a problem hiding this comment.
Pull request overview
Updates the documentation set for Phirewall 0.6, reflecting the new Config::with() / ConfigLayer composition model and the extraction of some functionality into companion preset packages, while adding new feature pages for trusted-bot verification and preset bundles.
Changes:
- Replaced legacy convenience calls (e.g.
trustedBots(),blocklists->owasp(),combine()/compose()/mergedWith()) with the 0.6-styleaddRule(...)andConfig::with(...)layering examples. - Documented new companion packages (OWASP CRS engine/presets, bot presets, bad-IP presets) and added dedicated feature pages.
- Updated navigation to surface the new feature documentation.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/getting-started.md | Updates quick-start snippets to new trusted-bot wiring API. |
| docs/features/trusted-bots.md | Adds dedicated page explaining DNS-verified trusted bot matching and usage patterns. |
| docs/features/safelists-blocklists.md | Updates safelist/blocklist docs for new addRule(...) patterns and OWASP companion package. |
| docs/features/owasp-crs.md | Migrates OWASP CRS docs to the companion package and adds preset-based quick starts. |
| docs/features/bot-presets.md | Adds companion bot/AI crawler preset package documentation. |
| docs/features/bot-detection.md | Updates bot detection docs to reflect new trusted-bot wiring and links to new page. |
| docs/features/bad-ip-preset.md | Adds companion bad-IP preset package documentation. |
| docs/faq.md | Updates OWASP CRS FAQ answers to the new companion package + addRule(...) usage. |
| docs/examples.md | Updates framework/PSR integration examples to new TrustedBot + OWASP CRS wiring. |
| docs/common-attacks.md | Updates OWASP CRS examples to companion package + addRule(...) usage. |
| docs/advanced/presets.md | Updates presets docs to Config::with() composition model. |
| docs/advanced/portable-config.md | Updates portable-config docs to Config::with() terminology and CRS note. |
| docs/advanced/config-composition.md | Rewrites composition docs around Config::with() and ConfigLayer. |
| docs/.vitepress/config.ts | Adds sidebar links for new feature pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| use Flowd\Phirewall\Config\Rule\SafelistRule; | ||
| use Flowd\Phirewall\Matchers\TrustedBotMatcher; | ||
|
|
||
| $config->safelists->addRule(new SafelistRule($name, new TrustedBotMatcher( |
Comment on lines
114
to
+118
| $config->safelists->ip('office', ['10.0.0.0/8', '192.168.1.0/24']); | ||
|
|
||
| // Safelist verified search engine bots (Googlebot, Bingbot, etc.). | ||
| // Verified via reverse DNS; pass a cache to skip repeat lookups (see Bot Detection). | ||
| $config->safelists->trustedBots(); | ||
| $config->safelists->addRule(new SafelistRule('trusted-bots', new TrustedBotMatcher())); |
| ## Trusted Bot Verification (rDNS) | ||
|
|
||
| The `trustedBots()` method safelists verified search engine bots using **reverse DNS (rDNS) verification**. This prevents fake bots: anyone can send `Googlebot` as a User-Agent, but only Google's real crawlers have IPs that resolve to `*.googlebot.com`. | ||
| Wiring a `TrustedBotMatcher` on the safelist safelists verified search engine bots using **reverse DNS (rDNS) verification**. This prevents fake bots: anyone can send `Googlebot` as a User-Agent, but only Google's real crawlers have IPs that resolve to `*.googlebot.com`. |
Comment on lines
+170
to
+173
| $config->safelists->addRule(new SafelistRule('trusted-bots', new TrustedBotMatcher( | ||
| ipResolver: $config->getIpResolver(), | ||
| cache: $cache, | ||
| ))); |
| ))); | ||
| ``` | ||
|
|
||
| Pass `ipResolver: $config->getIpResolver()` so verification uses the correct client IP behind a proxy. Omit it only if you deliberately want to verify against `REMOTE_ADDR`. |
| $config->fail2ban->add('persistent-attacker', | ||
| threshold: 5, period: 60, ban: 86400, | ||
| filter: fn($req) => true, | ||
| key: KeyExtractors::ip() |
| ))); | ||
| ``` | ||
|
|
||
| Pass `ipResolver: $config->getIpResolver()` so verification uses the real client IP behind a proxy, matching the [global IP resolver](#ip-resolution). |
Comment on lines
+118
to
+120
| $config->safelists->addRule(new SafelistRule('trusted-bots', new TrustedBotMatcher( | ||
| ipResolver: $config->getIpResolver(), | ||
| ))); |
| $config->safelists->addRule(new SafelistRule('bots', new TrustedBotMatcher([ | ||
| ['ua' => 'mypartnerbot', 'hostname' => '.partner.example.com'], | ||
| ]); | ||
| ], ipResolver: $config->getIpResolver()))); |
Comment on lines
+135
to
+138
| $config->safelists->addRule(new SafelistRule('trusted-bots', new TrustedBotMatcher( | ||
| ipResolver: $config->getIpResolver(), | ||
| cache: $cache, | ||
| ))); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.