anotherhadi/spilltea
1
Fork 0
mirror of https://github.com/anotherhadi/spilltea.git synced 2026-05-20 09:42:34 +02:00
Code Issues Packages Projects Releases Wiki Activity

Init

Browse Source 
Signed-off-by: Hadi <112569860+anotherhadi@users.noreply.github.com>
This commit is contained in:
Hadi
2026-05-12 19:12:29 +02:00
commit e8e64eff12
101 changed files with 10081 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/docs/certificate.md
+14
View File
@@ -0,0 +1,14 @@
## CA Certificate Installation
1. Copy your **CA Certificate** located in `{{.Cfg.App.CertDir}}`
2. Install your certificate:
- On Chrome:
- Open your Chrome settings, search for "Certificates" and click on "Security".
- In the security settings page, scroll down and click on "Manage certificates".
- Select the "Authorities" tab and click on "Import tab and click on "Import".
- Select the `mitmproxy-ca-cert.pem` file in `{{.Cfg.App.CertDir}}`.
- On Firefox:
- Open your Firefox settings, search for "Certificates" and click on "View Certificates".
- Select the "Authorities" tab and click on "Import".
- Select the `mitmproxy-ca-cert.pem` file in `{{.Cfg.App.CertDir}}`.
- When prompted, click the "Trust this CA to identify websites" checkbox, then click on "OK".
.github/docs/history.md
+25
View File
@@ -0,0 +1,25 @@
## History Search
The History page has a built-in search bar with two modes:
**Fulltext search**: press `/` to open it. Results filter in real time as you type across all fields: method, host, path, and the raw request/response bodies.
**SQL mode**: press `:` to open it, then `Enter` to run. You can write either a WHERE expression or a full SELECT query against the `entries` table.
WHERE expression (the `SELECT` is added automatically):
```sql
status_code = 404
```
```sql
host LIKE '%.api.%' AND method = 'POST'
```
Full SELECT query:
```sql
SELECT * FROM entries WHERE response_raw LIKE '%password%' ORDER BY timestamp DESC LIMIT 20
```
The `entries` table has the following columns: `id`, `timestamp`, `method`, `host`, `path`, `status_code`, `request_raw`, `response_raw`.
.github/docs/main.md
+15
View File
@@ -0,0 +1,15 @@
```txt
)
(
)
.-.,--^--. _
\\| `---' |//
\| /
_\_______/_
```
# Spilltea Documentation
- **Version**: `{{.Cfg.Version}}`
- **Repository**: `https://github.com/anotherhadi/spilltea`
- **Sponsor this project**: `https://ko-fi.com/anotherhadi`
.github/docs/plugins.md
+127
View File
@@ -0,0 +1,127 @@
# Plugins
Spilltea supports Lua plugins that can intercept, modify, and analyze HTTP traffic.
## Where to place plugins
Put `.lua` files in the directory configured by `plugins_dir` in your config file (default: `~/.config/spilltea/plugins`).
Each file is loaded as a separate plugin at startup. The plugin list is shown on the **Plugins** page.
## Plugin structure
Every plugin must declare a `Plugin` table and implement the hooks it wants to use.
```lua
Plugin = {
name = "My Plugin",
-- Declare which hooks you use and whether they are synchronous.
on_start = { sync = true },
on_request = { sync = true },
on_response = { sync = false },
on_history_entry = {},
on_quit = {},
}
```
### Hook reference
| Hook | When called | Sync/async | Return value |
| ------------------------- | --------------------------- | ------------ | ------------------- |
| `on_start(config_text)` | Once at startup | always sync | ignored |
| `on_quit()` | When the app exits | always sync | ignored |
| `on_request(req)` | Every request | declared | `"drop"`, `"forward"`, or `nil` (sync only) |
| `on_response(req, res)` | Every response | declared | `"drop"`, `"forward"`, or `nil` (sync only) |
| `on_history_entry(entry)` | After a flow is saved to DB | always async | ignored |
## Request and response objects
### `req` (request)
| Field / method | Type | Description |
| ----------------------------- | ------ | ----------------------------------- |
| `req.method` | string | HTTP method |
| `req.url` | string | Full URL |
| `req.host` | string | Host |
| `req.path` | string | Path |
| `req.headers["Name"]` | string | Request header value |
| `req:get_body()` | string | Raw request body (loaded on demand) |
| `req:set_header(name, value)` | - | Set a request header |
| `req:set_body(body)` | - | Replace the request body |
### `res` (response)
| Field / method | Type | Description |
| ----------------------------- | ------ | ------------------------- |
| `res.status_code` | number | HTTP status code |
| `res.headers["Name"]` | string | Response header value |
| `res:get_body()` | string | Raw response body |
| `res:set_header(name, value)` | - | Set a response header |
| `res:set_body(body)` | - | Replace the response body |
### `entry` (history entry)
| Field | Type |
| -------------------- | ---------------------------- |
| `entry.id` | number |
| `entry.method` | string |
| `entry.host` | string |
| `entry.path` | string |
| `entry.status_code` | number |
| `entry.timestamp` | string (YYYY-MM-DD HH:MM:SS) |
| `entry.request_raw` | string |
| `entry.response_raw` | string |
## Utility functions
```lua
-- Log a message to logs.log (prefixed with the plugin name)
log("message")
-- Send a notification bubble in the TUI
notif("Title", "Body text")
-- Create a finding (shown on the Findings page, persisted in DB)
create_finding({
title = "API Key Found",
description = "Markdown description of the finding...",
key = "stable-unique-id", -- used for deduplication; defaults to title
severity = "high", -- info | low | medium | high | critical
})
-- Check if a URL matches the current scope (whitelist/blacklist)
local ok = is_in_scope("https://example.com/api/v1")
-- Quit the app (useful for startup checks that fail)
quit("reason message")
```
### Finding deduplication
A finding is identified by `(plugin_name, key)`. If a finding with that pair already exists in the database it will **not** be re-created, even across restarts. If the user **dismisses** a finding it is permanently hidden and will never reappear, even if the plugin generates it again.
## Configuration
Each plugin gets a **config textarea** on the Plugins page. The raw text is passed as-is to `on_start(config_text)`. Parse it however you like (line by line, key=value, JSON, etc.).
## Sync vs async
- **`sync = true`**: spilltea waits for the hook to return before continuing. For `on_request`/`on_response` this blocks the proxy goroutine; the hook can return one of the values below.
- **`sync = false`** (or omitted for supported hooks): the hook runs in a background goroutine. Return values are ignored. Use this for analysis and findings.
### Return values for `on_request` and `on_response` (sync only)
| Return value | Effect |
| ------------ | ------ |
| `"drop"` | The flow is dropped immediately and never shown in the intercept panel. |
| `"forward"` | The flow is forwarded immediately without going through the intercept panel. |
| `nil` | Normal behaviour: the flow appears in the intercept panel for the user to decide. |
The `sync` declaration is only meaningful for `on_request` and `on_response`. The other hooks have fixed behaviour:
- `on_start` is **always synchronous**: plugins are initialised one by one before the first request is accepted.
- `on_quit` is **always synchronous**: the app waits for all `on_quit` hooks before exiting.
- `on_history_entry` is **always asynchronous**.
> A sync `on_request` or `on_response` hook that hangs will block traffic for that flow. There is no automatic timeout.
.github/docs/proxy.md
+9
View File
@@ -0,0 +1,9 @@
## Configuring your browser's proxy settings
We recommend installing **FoxyProxy** to manage your browser's proxies.
You can install it from the [Google Chrome extension store](https://chromewebstore.google.com/) or from the [Firefox extension store](https://addons.mozilla.org/en-US/firefox/extensions)
1. Open FoxyProxy's options, then click on `Add New Proxy` button.
2. Click the "Manual Proxy Configuration" radio button. Set the "HTTP Proxy" field to `{{.Cfg.App.Host}}` and the "Port" field to `{{.Cfg.App.Port}}`. Click "Save".
3. Forward traffic to Spilltea by selecting the new proxy in FoxyProxy's extension button.
4. You're all set! You can now use Spilltea.
.github/docs/scopes.md
+19
View File
@@ -0,0 +1,19 @@
## Scopes
Scopes let you control which requests Spilltea intercepts. Patterns are Go regular expressions matched against `host/path` (e.g. `api.example.com/v1/users`).
- **Whitelist**: if non-empty, only matching requests are intercepted.
- **Blacklist**: matching requests are always ignored, even if whitelisted.
When both lists are set, a request must pass the whitelist _and_ not be in the blacklist.
### Examples
| Pattern | Matches |
| -------------------------- | ----------------------------------- |
| `example\.com` | any request to `example.com` |
| `^api\.example\.com` | only the `api` subdomain |
| `example\.com/api/v2` | a specific path prefix |
| `\.(js\|css\|png\|woff2?)` | static assets (useful in blacklist) |
| `googleapis\.com` | all Google API traffic |
| `/graphql$` | any host with a `/graphql` endpoint |