diff options
46 files changed, 20879 insertions, 284 deletions
diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000..1636c48 --- /dev/null +++ b/.github/workflows/docs-deploy.yml @@ -0,0 +1,61 @@ +name: Docs deploy + +on: + workflow_dispatch: + push: + branches: [ "main" ] + +permissions: + contents: read + packages: write + attestations: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log into registry + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: techarohq + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Docker meta + id: meta + uses: docker/metadata-action@v5 + with: + images: ghcr.io/techarohq/anubis/docs + + - name: Build and push + id: build + uses: docker/build-push-action@v6 + with: + context: ./docs + cache-to: type=gha + cache-from: type=gha + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + platforms: linux/amd64 + push: true + + - name: Apply k8s manifests to aeacus + uses: actions-hub/kubectl@master + env: + KUBE_CONFIG: ${{ secrets.AEACUS_KUBECONFIG }} + with: + args: apply -k docs/manifest + + - name: Apply k8s manifests to aeacus + uses: actions-hub/kubectl@master + env: + KUBE_CONFIG: ${{ secrets.AEACUS_KUBECONFIG }} + with: + args: rollout restart -n default deploy/anubis-docs @@ -18,291 +18,10 @@ This is a bit of a nuclear response, but AI scraper bots scraping so aggressivel In most cases, you should not need this and can probably get by using Cloudflare to protect a given origin. However, for circumstances where you can't or won't use Cloudflare, Anubis is there for you. -If you want to try this out, connect to [git.xeserv.us](https://git.xeserv.us). +If you want to try this out, connect to [anubis.techaro.lol](https://anubis.techaro.lol). ## Support If you run into any issues running Anubis, please [open an issue](https://github.com/TecharoHQ/anubis/issues/new?template=Blank+issue) and tag it with the Anubis tag. Please include all the information I would need to diagnose your issue. For live chat, please join the [Patreon](https://patreon.com/cadey) and ask in the Patron discord in the channel `#anubis`. - -## How Anubis works - -Anubis uses a proof-of-work challenge to ensure that clients are using a modern browser and are able to calculate SHA-256 checksums. Anubis has a customizable difficulty for this proof-of-work challenge, but defaults to 5 leading zeroes. - -```mermaid ---- -title: Challenge generation and validation ---- - -flowchart TD - Backend("Backend") - Fail("Fail") - - style PresentChallenge color:#FFFFFF, fill:#AA00FF, stroke:#AA00FF - style ValidateChallenge color:#FFFFFF, fill:#AA00FF, stroke:#AA00FF - style Backend color:#FFFFFF, stroke:#00C853, fill:#00C853 - style Fail color:#FFFFFF, stroke:#FF2962, fill:#FF2962 - - subgraph Server - PresentChallenge("Present Challenge") - ValidateChallenge("Validate Challenge") - end - - subgraph Client - Main("main.mjs") - Worker("Worker") - end - - Main -- Request challenge --> PresentChallenge - PresentChallenge -- Return challenge & difficulty --> Main - Main -- Spawn worker --> Worker - Worker -- Successful challenge --> Main - Main -- Validate challenge --> ValidateChallenge - ValidateChallenge -- Return cookie --> Backend - ValidateChallenge -- If anything is wrong --> Fail -``` - -### Challenge presentation - -Anubis decides to present a challenge using this logic: - -- User-Agent contains `"Mozilla"` -- Request path is not in `/.well-known`, `/robots.txt`, or `/favicon.ico` -- Request path is not obviously an RSS feed (ends with `.rss`, `.xml`, or `.atom`) - -This should ensure that git clients, RSS readers, and other low-harm clients can get through without issue, but high-risk clients such as browsers and AI scraper bots will get blocked. - -```mermaid ---- -title: Challenge presentation logic ---- - -flowchart LR - Request("Request") - Backend("Backend") - %%Fail("Fail") - PresentChallenge("Present -challenge") - HasMozilla{"Is browser -or scraper?"} - HasCookie{"Has cookie?"} - HasExpired{"Cookie expired?"} - HasSignature{"Has valid -signature?"} - RandomJitter{"Secondary -screening?"} - POWPass{"Proof of -work valid?"} - - style PresentChallenge color:#FFFFFF, fill:#AA00FF, stroke:#AA00FF - style Backend color:#FFFFFF, stroke:#00C853, fill:#00C853 - %%style Fail color:#FFFFFF, stroke:#FF2962, fill:#FF2962 - - Request --> HasMozilla - HasMozilla -- Yes --> HasCookie - HasMozilla -- No --> Backend - HasCookie -- Yes --> HasExpired - HasCookie -- No --> PresentChallenge - HasExpired -- Yes --> PresentChallenge - HasExpired -- No --> HasSignature - HasSignature -- Yes --> RandomJitter - HasSignature -- No --> PresentChallenge - RandomJitter -- Yes --> POWPass - RandomJitter -- No --> Backend - POWPass -- Yes --> Backend - PowPass -- No --> PresentChallenge - PresentChallenge -- Back again for another cycle --> Request -``` - -### Proof of passing challenges - -When a client passes a challenge, Anubis sets an HTTP cookie named `"within.website-x-cmd-anubis-auth"` containing a signed [JWT](https://jwt.io/) (JSON Web Token). This JWT contains the following claims: - -- `challenge`: The challenge string derived from user request metadata -- `nonce`: The nonce / iteration number used to generate the passing response -- `response`: The hash that passed Anubis' checks -- `iat`: When the token was issued -- `nbf`: One minute prior to when the token was issued -- `exp`: The token's expiry week after the token was issued - -This ensures that the token has enough metadata to prove that the token is valid (due to the token's signature), but also so that the server can independently prove the token is valid. This cookie is allowed to be set without triggering an EU cookie banner notification; but depending on facts and circumstances, you may wish to disclose this to your users. - -### Challenge format - -Challenges are formed by taking some user request metadata and using that to generate a SHA-256 checksum. The following request headers are used: - -- `Accept-Encoding`: The content encodings that the requestor supports, such as gzip. -- `Accept-Language`: The language that the requestor would prefer the server respond in, such as English. -- `X-Real-Ip`: The IP address of the requestor, as set by a reverse proxy server. -- `User-Agent`: The user agent string of the requestor. -- The current time in UTC rounded to the nearest week. -- The fingerprint (checksum) of Anubis' private ED25519 key. - -This forms a fingerprint of the requestor using metadata that any requestor already is sending. It also uses time as an input, which is known to both the server and requestor due to the nature of linear timelines. Depending on facts and circumstances, you may wish to disclose this to your users. - -### JWT signing - -Anubis uses an ed25519 keypair to sign the JWTs issued when challenges are passed. Anubis will generate a new ed25519 keypair every time it starts. At this time, there is no way to share this keypair between instance of Anubis, but that will be addressed in future versions. - -## Setting up Anubis - -Anubis is meant to sit between your reverse proxy (such as Nginx or Caddy) and your target service. One instance of Anubis must be used per service you are protecting. - -Anubis is shipped in the Docker repo [`ghcr.io/techarohq/anubis`](https://github.com/TecharoHQ/anubis/pkgs/container/anubis). The following tags exist for your convenience: - -| Tag | Meaning | -| :------------ | :--------------------------------------------------------------------------------------------------------------------------------- | -| `latest` | The latest [tagged release](https://github.com/TecharoHQ/anubis/releases), if you are in doubt, start here. | -| `main` | The current build on the `main` branch. Only use this if you need the latest and greatest features as they are merged into `main`. | -| `pr-<number>` | The build associated with PR `#<number>`. Only use this for debugging issues fixed by a PR. | - -Other methods to install Anubis may exist, but the Docker image is currently the only supported method. - -The Docker image runs Anubis as user ID 1000 and group ID 1000. If you are mounting external volumes into Anubis' container, please be sure they are owned by or writable to this user/group. - -Anubis has very minimal system requirements. I suspect that 128Mi of ram may be sufficient for a large number of concurrent clients. Anubis may be a poor fit for apps that use WebSockets and maintain open connections, but I don't have enough real-world experience to know one way or another. - -Anubis uses these environment variables for configuration: - -| Environment Variable | Default value | Explanation | -| :------------------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `BIND` | `:8923` | The TCP port that Anubis listens on. | -| `DIFFICULTY` | `5` | The difficulty of the challenge, or the number of leading zeroes that must be in successful responses. | -| `METRICS_BIND` | `:9090` | The TCP port that Anubis serves Prometheus metrics on. | -| `POLICY_FNAME` | `/data/cfg/botPolicy.json` | The file containing [bot policy configuration](./docs/policies.md). See the bot policy documentation for more details. | -| `SERVE_ROBOTS_TXT` | `false` | If set `true`, Anubis will serve a default `robots.txt` file that disallows all known AI scrapers by name and then additionally disallows every scraper. This is useful if facts and circumstances make it difficult to change the underlying service to serve such a `robots.txt` file. | -| `TARGET` | `http://localhost:3923` | The URL of the service that Anubis should forward valid requests to. | - -### Policies - -Anubis has support for custom bot policies, matched by User-Agent string and request path. Check the [bot policy documentation](./docs/policies.md) for more information. - -### Docker compose - -Add Anubis to your compose file pointed at your service: - -```yaml -services: - anubis-nginx: - image: ghcr.io/techarohq/anubis:latest - environment: - BIND: ":8080" - DIFFICULTY: "5" - METRICS_BIND: ":9090" - SERVE_ROBOTS_TXT: "true" - TARGET: "http://nginx" - ports: - - 8080:8080 - nginx: - image: nginx - volumes: - - "./www:/usr/share/nginx/html" -``` - -### Kubernetes - -This example makes the following assumptions: - -- Your target service is listening on TCP port `5000`. -- Anubis will be listening on port `8080`. - -Attach Anubis to your Deployment: - -```yaml -containers: - # ... - - name: anubis - image: ghcr.io/techarohq/anubis:latest - imagePullPolicy: Always - env: - - name: "BIND" - value: ":8080" - - name: "DIFFICULTY" - value: "5" - - name: "METRICS_BIND" - value: ":9090" - - name: "SERVE_ROBOTS_TXT" - value: "true" - - name: "TARGET" - value: "http://localhost:5000" - resources: - limits: - cpu: 500m - memory: 128Mi - requests: - cpu: 250m - memory: 128Mi - securityContext: - runAsUser: 1000 - runAsGroup: 1000 - runAsNonRoot: true - allowPrivilegeEscalation: false - capabilities: - drop: - - ALL - seccompProfile: - type: RuntimeDefault -``` - -Then add a Service entry for Anubis: - -```diff -# ... - spec: - ports: -+ - protocol: TCP -+ port: 8080 -+ targetPort: 8080 -+ name: anubis -``` - -Then point your Ingress to the Anubis port: - -```diff - rules: - - host: git.xeserv.us - http: - paths: - - pathType: Prefix - path: "/" - backend: - service: - name: git - port: -- name: http -+ name: anubis -``` - -## Known caveats - -Anubis works with most programs without any issues as long as they're configured to trust `127.0.0.0/8` and `::1/128` as "valid proxy servers". Some combinations of reverse proxy and target application can have issues. This section documents them so that you can pattern-match and fix them. - -### Caddy + Gitea/Forgejo - -Gitea/Forgejo relies on the reverse proxy setting the `X-Real-Ip` header. Caddy does not do this out of the gate. Modify your Caddyfile like this: - -```diff - ellenjoe.int.within.lgbt { - # ... -- reverse_proxy http://localhost:3000 -+ reverse_proxy http://localhost:3000 { -+ header_up X-Real-Ip {remote_host} -+ } - # ... - } -``` - -Ensure that Gitea/Forgejo have `[security].REVERSE_PROXY_TRUSTED_PROXIES` set to the IP ranges that Anubis will appear from. Typically this is sufficient: - -```ini -[security] -REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.0/8,::1/128 -``` - -However if you are running Anubis in a separate Pod/Deployment in Kubernetes, you may have to adjust this to the IP range of the Pod space in your Container Networking Interface plugin: - -```ini -[security] -REVERSE_PROXY_TRUSTED_PROXIES = 10.192.0.0/12 -``` diff --git a/docs/.dockerignore b/docs/.dockerignore new file mode 100644 index 0000000..13ad2b9 --- /dev/null +++ b/docs/.dockerignore @@ -0,0 +1,23 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Kubernetes manifests +/manifest
\ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..b2d6de3 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,20 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000..0faa826 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,10 @@ +FROM node AS build + +WORKDIR /app +COPY . . + +RUN npm ci && npm run build + +FROM nginx:alpine +COPY --from=build /app/build /usr/share/nginx/html +LABEL org.opencontainers.image.source="https://github.com/TecharoHQ/anubis"
\ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..0c6c2c2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,41 @@ +# Website + +This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. + +### Installation + +``` +$ yarn +``` + +### Local Development + +``` +$ yarn start +``` + +This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. + +### Build + +``` +$ yarn build +``` + +This command generates static content into the `build` directory and can be served using any static contents hosting service. + +### Deployment + +Using SSH: + +``` +$ USE_SSH=true yarn deploy +``` + +Not using SSH: + +``` +$ GIT_USER=<Your GitHub username> yarn deploy +``` + +If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. diff --git a/docs/blog/2019-05-28-first-blog-post.md b/docs/blog/2019-05-28-first-blog-post.md new file mode 100644 index 0000000..d3032ef --- /dev/null +++ b/docs/blog/2019-05-28-first-blog-post.md @@ -0,0 +1,12 @@ +--- +slug: first-blog-post +title: First Blog Post +authors: [slorber, yangshun] +tags: [hola, docusaurus] +--- + +Lorem ipsum dolor sit amet... + +<!-- truncate --> + +...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/docs/blog/2019-05-29-long-blog-post.md b/docs/blog/2019-05-29-long-blog-post.md new file mode 100644 index 0000000..eb4435d --- /dev/null +++ b/docs/blog/2019-05-29-long-blog-post.md @@ -0,0 +1,44 @@ +--- +slug: long-blog-post +title: Long Blog Post +authors: yangshun +tags: [hello, docusaurus] +--- + +This is the summary of a very long blog post, + +Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view. + +<!-- truncate --> + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/docs/blog/2021-08-01-mdx-blog-post.mdx b/docs/blog/2021-08-01-mdx-blog-post.mdx new file mode 100644 index 0000000..0c4b4a4 --- /dev/null +++ b/docs/blog/2021-08-01-mdx-blog-post.mdx @@ -0,0 +1,24 @@ +--- +slug: mdx-blog-post +title: MDX Blog Post +authors: [slorber] +tags: [docusaurus] +--- + +Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/). + +:::tip + +Use the power of React to create interactive blog posts. + +::: + +{/* truncate */} + +For example, use JSX to create an interactive button: + +```js +<button onClick={() => alert('button clicked!')}>Click me!</button> +``` + +<button onClick={() => alert('button clicked!')}>Click me!</button> diff --git a/docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg Binary files differnew file mode 100644 index 0000000..11bda09 --- /dev/null +++ b/docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg diff --git a/docs/blog/2021-08-26-welcome/index.md b/docs/blog/2021-08-26-welcome/index.md new file mode 100644 index 0000000..349ea07 --- /dev/null +++ b/docs/blog/2021-08-26-welcome/index.md @@ -0,0 +1,29 @@ +--- +slug: welcome +title: Welcome +authors: [slorber, yangshun] +tags: [facebook, hello, docusaurus] +--- + +[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog). + +Here are a few tips you might find useful. + +<!-- truncate --> + +Simply add Markdown files (or folders) to the `blog` directory. + +Regular blog authors can be added to `authors.yml`. + +The blog post date can be extracted from filenames, such as: + +- `2019-05-30-welcome.md` +- `2019-05-30-welcome/index.md` + +A blog post folder can be convenient to co-locate blog post images: + + + +The blog supports tags as well! + +**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config. diff --git a/docs/blog/authors.yml b/docs/blog/authors.yml new file mode 100644 index 0000000..8bfa5c7 --- /dev/null +++ b/docs/blog/authors.yml @@ -0,0 +1,23 @@ +yangshun: + name: Yangshun Tay + title: Front End Engineer @ Facebook + url: https://github.com/yangshun + image_url: https://github.com/yangshun.png + page: true + socials: + x: yangshunz + github: yangshun + +slorber: + name: Sébastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png + page: + # customize the url of the author page at /blog/authors/<permalink> + permalink: '/all-sebastien-lorber-articles' + socials: + x: sebastienlorber + linkedin: sebastienlorber + github: slorber + newsletter: https://thisweekinreact.com diff --git a/docs/blog/tags.yml b/docs/blog/tags.yml new |
