diff options
| -rw-r--r-- | docs/docs/CHANGELOG.md | 1 | ||||
| -rw-r--r-- | docs/docs/admin/default-allow-behavior.mdx | 92 | ||||
| -rw-r--r-- | docs/docs/admin/policies.mdx | 2 |
3 files changed, 94 insertions, 1 deletions
diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index c5a8484..fc949e3 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +- Add documentation for default allow behavior (implicit rule) - Enable [importing configuration snippets](./admin/configuration/import.mdx) ([#321](https://github.com/TecharoHQ/anubis/pull/321)) - Refactor check logic to be more generic and work on a Checker type - Add more AI user agents based on the [ai.robots.txt](https://github.com/ai-robots-txt/ai.robots.txt) project diff --git a/docs/docs/admin/default-allow-behavior.mdx b/docs/docs/admin/default-allow-behavior.mdx new file mode 100644 index 0000000..6249e73 --- /dev/null +++ b/docs/docs/admin/default-allow-behavior.mdx @@ -0,0 +1,92 @@ +--- +title: Default allow behavior +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Default allow behavior + +Anubis is designed to be as unintrusive as possible to your existing infrastructure. + +By default, it allows all traffic unless a request matches a rule that explicitly denies or challenges it. + +Only requests matching a DENY or CHALLENGE rule are blocked or challenged. All other requests are allowed. This is called "the implicit rule". + +## Example: Minimal policy + +If your policy only blocks a specific bot, all other requests will be allowed: + +<Tabs> +<TabItem value="json" label="JSON" default> + +```json +{ + "bots": [ + { + "name": "block-amazonbot", + "user_agent_regex": "Amazonbot", + "action": "DENY" + } + ] +} +``` + +</TabItem> +<TabItem value="yaml" label="YAML"> + +```yaml +- name: block-amazonbot + user_agent_regex: Amazonbot + action: DENY +``` + +</TabItem> +</Tabs> + +## How to deny by default + +If you want to deny all traffic except what you explicitly allow, add a catch-all deny rule at the end of your policy list. Make sure to add ALLOW rules for any traffic you want to permit before this rule. + +<Tabs> +<TabItem value="json" label="JSON" default> + +```json +{ + "bots": [ + { + "name": "allow-goodbot", + "user_agent_regex": "GoodBot", + "action": "ALLOW" + }, + { + "name": "catch-all-deny", + "path_regex": ".*", + "action": "DENY" + } + ] +} +``` + +</TabItem> +<TabItem value="yaml" label="YAML"> + +```yaml +- name: allow-goodbot + user_agent_regex: GoodBot + action: ALLOW +- name: catch-all-deny + path_regex: .* + action: DENY +``` + +</TabItem> +</Tabs> + +## Final remarks + +- Rules are evaluated in order; the first match wins. +- The implicit allow rule is always last and cannot be removed. +- Use your logs to monitor what traffic is being allowed by default. + +See [Policy Definitions](./policies) for more details on writing rules.
\ No newline at end of file diff --git a/docs/docs/admin/policies.mdx b/docs/docs/admin/policies.mdx index b23a62f..975faef 100644 --- a/docs/docs/admin/policies.mdx +++ b/docs/docs/admin/policies.mdx @@ -112,7 +112,7 @@ bots: This allows requests to [`/.well-known`](https://en.wikipedia.org/wiki/Well-known_URI), `/favicon.ico`, `/robots.txt`, and challenges any request that has the word `Mozilla` in its User-Agent string. The [default policy file](https://github.com/TecharoHQ/anubis/blob/main/data/botPolicies.json) is a bit more cohesive, but this should be more than enough for most users. -If no rules match the request, it is allowed through. +If no rules match the request, it is allowed through. For more details on this default behavior and its implications, see [Default allow behavior](./default-allow-behavior.mdx). ## Writing your own rules |