WIP: docs (#176)

Initial version of documentation
nt0xa · Aug 18, 2024 · 202ce3a · 202ce3a
1 parent 4570a1c
commit 202ce3a
Show file tree

Hide file tree

Showing 134 changed files with 17,278 additions and 11 deletions.
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,54 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+
+defaults:
+  run:
+    working-directory: ./docs
+
+jobs:
+  build:
+    name: Build docs 
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: ./docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build website
+        run: npm run build
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy docs to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml
@@ -0,0 +1,31 @@
+name: Test docs deployment
+
+on:
+  pull_request:
+    branches:
+      - master
+
+defaults:
+  run:
+    working-directory: ./docs
+
+jobs:
+  test-deploy:
+    name: Test docs deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: ./docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Test build website
+        run: npm run build
diff --git a/Makefile b/Makefile
@@ -30,9 +30,14 @@ build/client:
 #
 
 .PHONY: dev
-dev:
+dev/server:
 	@$(LOCAL_BIN)/air
 
+.PHONY: dev/docs
+dev/docs:
+	cd docs && npm start
+
+
 #
 # Completions
 #

diff --git a/cmd/server/main.go b/cmd/server/main.go
@@ -153,7 +153,7 @@ func serve(cfg *server.Config) {
 
 	go func() {
 		srv := dnsx.New(
-			":53",
+			":5053",
 			dnsHandler,
 			dnsx.NotifyStartedFunc(waitDNS.Done),
 		)

diff --git a/docs/.gitignore 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/README.md b/docs/README.md
@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ npm install
+```
+
+### Local Development
+
+```
+$ npm run 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
+
+```
+$ npm run 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 npm run deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> npm run 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/babel.config.js b/docs/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/docs/docs/assets/clear_all_telegram_dark.png b/docs/docs/assets/clear_all_telegram_dark.png
diff --git a/docs/docs/assets/clear_all_telegram_light.png b/docs/docs/assets/clear_all_telegram_light.png
diff --git a/docs/docs/assets/clear_telegram_dark.png b/docs/docs/assets/clear_telegram_dark.png
diff --git a/docs/docs/assets/clear_telegram_light.png b/docs/docs/assets/clear_telegram_light.png
diff --git a/docs/docs/assets/create_payload_cli_dark.png b/docs/docs/assets/create_payload_cli_dark.png
diff --git a/docs/docs/assets/create_payload_cli_light.png b/docs/docs/assets/create_payload_cli_light.png
diff --git a/docs/docs/assets/create_payload_events_telegram_dark.png b/docs/docs/assets/create_payload_events_telegram_dark.png
diff --git a/docs/docs/assets/create_payload_events_telegram_light.png b/docs/docs/assets/create_payload_events_telegram_light.png
diff --git a/docs/docs/assets/create_payload_protocols_telegram_dark.png b/docs/docs/assets/create_payload_protocols_telegram_dark.png
diff --git a/docs/docs/assets/create_payload_protocols_telegram_light.png b/docs/docs/assets/create_payload_protocols_telegram_light.png
diff --git a/docs/docs/assets/create_payload_telegram_dark.png b/docs/docs/assets/create_payload_telegram_dark.png
diff --git a/docs/docs/assets/create_payload_telegram_light.png b/docs/docs/assets/create_payload_telegram_light.png
diff --git a/docs/docs/assets/dns_clear_telegram_dark.png b/docs/docs/assets/dns_clear_telegram_dark.png
diff --git a/docs/docs/assets/dns_clear_telegram_light.png b/docs/docs/assets/dns_clear_telegram_light.png
diff --git a/docs/docs/assets/dns_del_telegram_dark.png b/docs/docs/assets/dns_del_telegram_dark.png
diff --git a/docs/docs/assets/dns_del_telegram_light.png b/docs/docs/assets/dns_del_telegram_light.png
diff --git a/docs/docs/assets/dns_list_telegram_dark.png b/docs/docs/assets/dns_list_telegram_dark.png
diff --git a/docs/docs/assets/dns_list_telegram_light.png b/docs/docs/assets/dns_list_telegram_light.png
diff --git a/docs/docs/assets/dns_new_multiple_telegram_dark.png b/docs/docs/assets/dns_new_multiple_telegram_dark.png
diff --git a/docs/docs/assets/dns_new_multiple_telegram_light.png b/docs/docs/assets/dns_new_multiple_telegram_light.png
diff --git a/docs/docs/assets/dns_new_rebind_telegram_dark.png b/docs/docs/assets/dns_new_rebind_telegram_dark.png
diff --git a/docs/docs/assets/dns_new_rebind_telegram_light.png b/docs/docs/assets/dns_new_rebind_telegram_light.png
diff --git a/docs/docs/assets/dns_new_telegram_dark.png b/docs/docs/assets/dns_new_telegram_dark.png
diff --git a/docs/docs/assets/dns_new_telegram_light.png b/docs/docs/assets/dns_new_telegram_light.png
diff --git a/docs/docs/assets/dns_new_wildcard_telegram_dark.png b/docs/docs/assets/dns_new_wildcard_telegram_dark.png
diff --git a/docs/docs/assets/dns_new_wildcard_telegram_light.png b/docs/docs/assets/dns_new_wildcard_telegram_light.png
diff --git a/docs/docs/assets/dns_notification_dark.png b/docs/docs/assets/dns_notification_dark.png
diff --git a/docs/docs/assets/dns_notification_light.png b/docs/docs/assets/dns_notification_light.png
diff --git a/docs/docs/assets/dns_test_alert_multiple_telegram_dark.png b/docs/docs/assets/dns_test_alert_multiple_telegram_dark.png
diff --git a/docs/docs/assets/dns_test_alert_multiple_telegram_light.png b/docs/docs/assets/dns_test_alert_multiple_telegram_light.png
diff --git a/docs/docs/assets/dns_test_alert_rebind_telegram_dark.png b/docs/docs/assets/dns_test_alert_rebind_telegram_dark.png
diff --git a/docs/docs/assets/dns_test_alert_rebind_telegram_light.png b/docs/docs/assets/dns_test_alert_rebind_telegram_light.png
diff --git a/docs/docs/assets/dns_test_alert_telegram_dark.png b/docs/docs/assets/dns_test_alert_telegram_dark.png
diff --git a/docs/docs/assets/dns_test_alert_telegram_light.png b/docs/docs/assets/dns_test_alert_telegram_light.png
diff --git a/docs/docs/assets/dns_test_alert_wildcard_telegram_dark.png b/docs/docs/assets/dns_test_alert_wildcard_telegram_dark.png
diff --git a/docs/docs/assets/dns_test_alert_wildcard_telegram_light.png b/docs/docs/assets/dns_test_alert_wildcard_telegram_light.png
diff --git a/docs/docs/assets/dns_test_dark.png b/docs/docs/assets/dns_test_dark.png
diff --git a/docs/docs/assets/dns_test_light.png b/docs/docs/assets/dns_test_light.png
diff --git a/docs/docs/assets/dns_test_multiple_dark.png b/docs/docs/assets/dns_test_multiple_dark.png
diff --git a/docs/docs/assets/dns_test_multiple_light.png b/docs/docs/assets/dns_test_multiple_light.png
diff --git a/docs/docs/assets/dns_test_rebind_1_dark.png b/docs/docs/assets/dns_test_rebind_1_dark.png
diff --git a/docs/docs/assets/dns_test_rebind_1_light.png b/docs/docs/assets/dns_test_rebind_1_light.png
diff --git a/docs/docs/assets/dns_test_wildcard_dark.png b/docs/docs/assets/dns_test_wildcard_dark.png
diff --git a/docs/docs/assets/dns_test_wildcard_light.png b/docs/docs/assets/dns_test_wildcard_light.png
diff --git a/docs/docs/assets/events_get_telegram_dark.png b/docs/docs/assets/events_get_telegram_dark.png
diff --git a/docs/docs/assets/events_get_telegram_light.png b/docs/docs/assets/events_get_telegram_light.png
diff --git a/docs/docs/assets/events_list_first_telegram_dark.png b/docs/docs/assets/events_list_first_telegram_dark.png
diff --git a/docs/docs/assets/events_list_first_telegram_light.png b/docs/docs/assets/events_list_first_telegram_light.png
diff --git a/docs/docs/assets/events_list_mn2_telegram_dark.png b/docs/docs/assets/events_list_mn2_telegram_dark.png
diff --git a/docs/docs/assets/events_list_mn2_telegram_light.png b/docs/docs/assets/events_list_mn2_telegram_light.png
diff --git a/docs/docs/assets/events_list_mn_telegram_dark.png b/docs/docs/assets/events_list_mn_telegram_dark.png
diff --git a/docs/docs/assets/events_list_mn_telegram_light.png b/docs/docs/assets/events_list_mn_telegram_light.png
diff --git a/docs/docs/assets/events_list_n_telegram_dark.png b/docs/docs/assets/events_list_n_telegram_dark.png
diff --git a/docs/docs/assets/events_list_n_telegram_light.png b/docs/docs/assets/events_list_n_telegram_light.png
diff --git a/docs/docs/assets/events_list_telegram_dark.png b/docs/docs/assets/events_list_telegram_dark.png
diff --git a/docs/docs/assets/events_list_telegram_light.png b/docs/docs/assets/events_list_telegram_light.png
diff --git a/docs/docs/assets/example_notification.png b/docs/docs/assets/example_notification.png
diff --git a/docs/docs/assets/ftp_notification_dark.png b/docs/docs/assets/ftp_notification_dark.png
diff --git a/docs/docs/assets/ftp_notification_light.png b/docs/docs/assets/ftp_notification_light.png
diff --git a/docs/docs/assets/http_clear_telegram_dark.png b/docs/docs/assets/http_clear_telegram_dark.png
diff --git a/docs/docs/assets/http_clear_telegram_light.png b/docs/docs/assets/http_clear_telegram_light.png
diff --git a/docs/docs/assets/http_del_telegram_dark.png b/docs/docs/assets/http_del_telegram_dark.png
diff --git a/docs/docs/assets/http_del_telegram_light.png b/docs/docs/assets/http_del_telegram_light.png
diff --git a/docs/docs/assets/http_list_telegram_dark.png b/docs/docs/assets/http_list_telegram_dark.png
diff --git a/docs/docs/assets/http_list_telegram_light.png b/docs/docs/assets/http_list_telegram_light.png
diff --git a/docs/docs/assets/http_new_dynamic_all_telegram_dark.png b/docs/docs/assets/http_new_dynamic_all_telegram_dark.png
diff --git a/docs/docs/assets/http_new_dynamic_all_telegram_light.png b/docs/docs/assets/http_new_dynamic_all_telegram_light.png
diff --git a/docs/docs/assets/http_new_dynamic_telegram_dark.png b/docs/docs/assets/http_new_dynamic_telegram_dark.png
diff --git a/docs/docs/assets/http_new_dynamic_telegram_light.png b/docs/docs/assets/http_new_dynamic_telegram_light.png
diff --git a/docs/docs/assets/http_new_redirect_telegram_dark.png b/docs/docs/assets/http_new_redirect_telegram_dark.png
diff --git a/docs/docs/assets/http_new_redirect_telegram_light.png b/docs/docs/assets/http_new_redirect_telegram_light.png
diff --git a/docs/docs/assets/http_notification_dark.png b/docs/docs/assets/http_notification_dark.png
diff --git a/docs/docs/assets/http_notification_light.png b/docs/docs/assets/http_notification_light.png
diff --git a/docs/docs/assets/http_test_alert_dynamic_all_telegram_dark.png b/docs/docs/assets/http_test_alert_dynamic_all_telegram_dark.png
diff --git a/docs/docs/assets/http_test_alert_dynamic_all_telegram_light.png b/docs/docs/assets/http_test_alert_dynamic_all_telegram_light.png
diff --git a/docs/docs/assets/http_test_alert_dynamic_telegram_dark.png b/docs/docs/assets/http_test_alert_dynamic_telegram_dark.png
diff --git a/docs/docs/assets/http_test_alert_dynamic_telegram_light.png b/docs/docs/assets/http_test_alert_dynamic_telegram_light.png
diff --git a/docs/docs/assets/http_test_alert_redirect_telegram_dark.png b/docs/docs/assets/http_test_alert_redirect_telegram_dark.png
diff --git a/docs/docs/assets/http_test_alert_redirect_telegram_light.png b/docs/docs/assets/http_test_alert_redirect_telegram_light.png
diff --git a/docs/docs/assets/http_test_dynamic_all_dark.png b/docs/docs/assets/http_test_dynamic_all_dark.png
diff --git a/docs/docs/assets/http_test_dynamic_all_light.png b/docs/docs/assets/http_test_dynamic_all_light.png
diff --git a/docs/docs/assets/http_test_dynamic_dark.png b/docs/docs/assets/http_test_dynamic_dark.png
diff --git a/docs/docs/assets/http_test_dynamic_light.png b/docs/docs/assets/http_test_dynamic_light.png
diff --git a/docs/docs/assets/http_test_redirect_dark.png b/docs/docs/assets/http_test_redirect_dark.png
diff --git a/docs/docs/assets/http_test_redirect_light.png b/docs/docs/assets/http_test_redirect_light.png
diff --git a/docs/docs/assets/list_payloads_filter_telegram_dark.png b/docs/docs/assets/list_payloads_filter_telegram_dark.png
diff --git a/docs/docs/assets/list_payloads_filter_telegram_light.png b/docs/docs/assets/list_payloads_filter_telegram_light.png
diff --git a/docs/docs/assets/list_payloads_telegram_dark.png b/docs/docs/assets/list_payloads_telegram_dark.png
diff --git a/docs/docs/assets/list_payloads_telegram_light.png b/docs/docs/assets/list_payloads_telegram_light.png
diff --git a/docs/docs/assets/modify_payload_events_telegram_dark.png b/docs/docs/assets/modify_payload_events_telegram_dark.png
diff --git a/docs/docs/assets/modify_payload_events_telegram_light.png b/docs/docs/assets/modify_payload_events_telegram_light.png
diff --git a/docs/docs/assets/modify_payload_telegram_dark.png b/docs/docs/assets/modify_payload_telegram_dark.png
diff --git a/docs/docs/assets/modify_payload_telegram_light.png b/docs/docs/assets/modify_payload_telegram_light.png
diff --git a/docs/docs/assets/smtp_notification_dark.png b/docs/docs/assets/smtp_notification_dark.png
diff --git a/docs/docs/assets/smtp_notification_eml_dark.png b/docs/docs/assets/smtp_notification_eml_dark.png
diff --git a/docs/docs/assets/smtp_notification_eml_light.png b/docs/docs/assets/smtp_notification_eml_light.png
diff --git a/docs/docs/assets/smtp_notification_light.png b/docs/docs/assets/smtp_notification_light.png
diff --git a/docs/docs/assets/telegram_token_dark.png b/docs/docs/assets/telegram_token_dark.png
diff --git a/docs/docs/assets/telegram_token_light.png b/docs/docs/assets/telegram_token_light.png
diff --git a/docs/docs/guides/_category_.json b/docs/docs/guides/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Usage",
+  "position": 3
+}
diff --git a/docs/docs/guides/alerts.md b/docs/docs/guides/alerts.md
@@ -0,0 +1,49 @@
+---
+sidebar_position: 2
+---
+
+# Alerts
+
+## DNS
+
+- DNS listener runs on port **53**.
+- You will receive notifications for any DNS queries of your payload's domain (e.g. `d14a68e4.sonar.test`)
+  and for any queries of its subdomains (e.g. `test.d14a68e4.sonar.test`).
+- A notification is a dig-like representation of a DNS question and its answer.
+
+  ![DNS notification example](../assets/dns_notification_dark.png#gh-dark-mode-only)![DNS notification example](../assets/dns_notification_light.png#gh-light-mode-only)
+
+## HTTP
+
+- HTTP listener runs on port **80**, HTTPS on port **443**.
+- You will receive notifications for any HTTP(s) request that contains your subdomain (e.g. `d14a68e4`) **anywhere in the request**.
+  It doesn't matter if it is in the `Host` header or any other header or body.
+- ⚠️ HTTP/2 and HTTP/3 are not supported yet, **only HTTP/1.1**.
+- ⚠️ You can also use subdomains on your payload domain (i.e. `test.d14a68e4.sonar.test`), but
+  the Sonar server won't automatically request a TLS certificate for them (it only requests `*.<DOMAIN>` certificate),
+  so remote HTTPS client will most likely get a certificate validation error for them.
+- A notification is an HTTP request and its response:
+
+  ![HTTP notification](../assets/http_notification_dark.png#gh-dark-mode-only)![HTTP notification](../assets/http_notification_light.png#gh-light-mode-only)
+
+## SMTP
+
+- SMTP listener runs on port **25**.
+- `STARTTLS` is supported.
+- You will receive notifications for any SMTP session that contains you subdomain (e.g. `d14a68e4`) **anywhere** in it.
+- A notification is a full log of SMTP session:
+
+  ![SMTP notification](../assets/smtp_notification_dark.png#gh-dark-mode-only)![SMTP notification](../assets/smtp_notification_light.png#gh-light-mode-only)
+
+- Additionally you will receive `.eml` file with a content of email. This file can be opened in any email client to view the rendered content.
+
+  ![SMTP notification EML](../assets/smtp_notification_eml_dark.png#gh-dark-mode-only)![SMTP notification EML](../assets/smtp_notification_eml_light.png#gh-light-mode-only)
+
+## FTP
+
+- FTP listener runs on port **21**.
+- ⚠️ To receive an FTP notification, your unique domain (e.g. `d14a68e4`) must appear somewhere in the FTP communication log.
+  You can achieve this by adding the domain to the user/password or file name, like this: `ftp://d14a68e4:[email protected]` or `ftp://sonar.test/d14a68e4`.
+- A notification is a full FTP session log.
+
+  ![FTP notification](../assets/ftp_notification_dark.png#gh-dark-mode-only)![FTP notification](../assets/ftp_notification_light.png#gh-light-mode-only)