Skip to content

KALI_USAGE.md

Latest commit

 

History

History
761 lines (550 loc) · 13.9 KB

KALI_USAGE.md

File metadata and controls

761 lines (550 loc) · 13.9 KB
Raw

Project Lethe Kali Linux Usage Guide

Project Lethe is a lightweight CLI for authorized WAF resilience testing. It can profile an in-scope URL, ask an AI provider for a safety-first test plan, and generate deterministic payload variants using allowlisted transformations.

Use this only on systems you own, administer, or have explicit permission to test.

1. Install System Requirements

Kali usually includes Python, but install the basics first:

sudo apt update
sudo apt install -y git python3 python3-venv python3-pip

Check Python:

python3 --version

Project Lethe requires Python 3.10 or newer.

2. Clone The Repository

git clone https://github.com/styxabhor/Project-Lethe.git
cd Project-Lethe

If you already have the project folder on Kali, just enter it:

cd project-lethe

3. Create A Virtual Environment

python3 -m venv .venv
source .venv/bin/activate

Your shell should now show (.venv).

4. Install Project Lethe

Install it in editable mode:

pip install -e .

Confirm it works:

lethe --version
lethe --help

Expected version at the time this guide was written:

Project Lethe 0.11.0

5. Optional Config File

Copy the example config:

cp .lethe.toml.example .lethe.toml

Edit it:

nano .lethe.toml

Basic config:

[lethe]
profile = "xss"
limit = 25
max_depth = 2
format = "table"
table_width = 96
include_baseline = false
banner = true
profile_timeout = 10

Check resolved config:

lethe config

Ignore config for one command:

lethe --no-config generate --payload '<test>'

6. Generate Payload Variants

Basic usage:

lethe generate --payload '<waf-test data-id="123">' --profile xss --limit 12

JSON output:

lethe generate \
  --payload '<waf-test data-id="123">' \
  --profile xss \
  --limit 12 \
  --format json

Markdown report output:

lethe generate \
  --payload '<waf-test data-id="123">' \
  --profile xss \
  --limit 12 \
  --format markdown

Use only one technique tag:

lethe generate --payload 'abc def' --profile generic --tag unicode

List profiles:

lethe profiles

List tags:

lethe tags

List techniques:

lethe techniques
lethe techniques --tag unicode

7. Advanced Novelty Mode

This mode is for simulating unseen WAF normalization cases in authorized labs. It does not generate real zero-day exploits. It combines allowlisted local transformations and bounded randomized padding.

Stack multiple mutation layers:

lethe generate \
  --payload '<waf-test data-id="123">' \
  --profile xss \
  --stack 3 \
  --limit 75

Default stack depth is capped at 4 to avoid runaway output. For local labs, you can allow depths up to 6:

lethe generate \
  --payload '<test>' \
  --stack 5 \
  --allow-deep-stack \
  --limit 100

Explore novelty-oriented parser, Unicode, entity, recursive, and canonicalization techniques:

lethe generate \
  --payload '<waf-test>' \
  --explore \
  --format json

Preview the resolved plan without generating variants:

lethe generate \
  --payload '<waf-test>' \
  --explore \
  --stack 3 \
  --dry-run \
  --format json

Add bounded polymorphic padding variants:

lethe generate \
  --payload '<waf-test>' \
  --profile xss \
  --limit 40 \
  --polymorphic 10 \
  --poly-seed report-001 \
  --format markdown

Use a specific polymorphic style:

lethe generate --payload '<test>' --polymorphic 5 --poly-style zero-width
lethe generate --payload '/search?q=test' --polymorphic 5 --poly-style query-pad

Useful styles:

  • mixed: rotates between safe padding styles.
  • html-comment: wraps with HTML comment canaries.
  • block-comment: wraps with block comment canaries.
  • zero-width: inserts invisible Unicode separators.
  • query-pad: appends a harmless lethe_pad_* query parameter.

Use --poly-seed when you need reproducible output for a report.

8. Explain A Technique

Use explain when you want report-friendly proof of how a transformation changed your test string:

lethe explain --payload '<waf-test>' --technique html_hex_entities

Markdown:

lethe explain \
  --payload '<waf-test>' \
  --technique html_hex_entities \
  --format markdown

Explain a stacked transformation chain:

lethe explain \
  --payload '<waf-test>' \
  --technique html_hex_entities \
  --technique url_encode_reserved

9. Analyze A Variant For Reports

Use analyze when you need triage-ready language explaining why a transformed variant matters. It outputs normalization hypotheses, evidence notes, safe validation guidance, remediation, and a character-level diff.

Analyze a known Lethe technique chain:

lethe analyze \
  --payload '<waf-test>' \
  --technique html_hex_entities \
  --technique url_encode_reserved \
  --profile xss \
  --format markdown

Analyze a copied variant from a previous run:

lethe analyze \
  --payload '<waf-test>' \
  --mutated '%3Cwaf-test%3E' \
  --format markdown

Add an AI narrative using a local Ollama model:

lethe analyze \
  --payload '<waf-test>' \
  --technique html_hex_entities \
  --ai-provider ollama \
  --ai-model qwen3:8b \
  --format markdown

Demo the AI flow without an API key:

lethe analyze \
  --payload '<waf-test>' \
  --technique html_hex_entities \
  --ai-command 'python examples/mock_ai_analysis.py' \
  --format markdown

The AI analysis mode is explanation-only. It is instructed not to invent new payloads, bypasses, exploit code, scanning steps, or mutation ideas.

10. Profile An Authorized URL

Profile mode makes one request to an in-scope URL and returns response context. It helps Lethe choose better profiles and technique tags.

lethe profile https://example.com/account --format json --output site-profile.json

Use the site profile during generation:

lethe generate \
  --payload '<waf-test>' \
  --site-profile site-profile.json \
  --limit 12

Optional reflection check with a harmless canary:

lethe profile https://example.com/search --reflect

11. Authenticated Profiling

Prefer environment variables so secrets do not land in shell history.

Bearer token example:

export LETHE_TOKEN='redacted-token-here'

lethe profile https://example.com/account \
  --bearer-token-env LETHE_TOKEN \
  --format json \
  --output site-profile.json

Cookie example:

export LETHE_COOKIE='session=redacted'

lethe profile https://example.com/account \
  --cookie-env LETHE_COOKIE \
  --format json \
  --output site-profile.json

Custom header example:

lethe profile https://example.com/account \
  --header 'X-Program-Scope: authorized' \
  --format json \
  --output site-profile.json

12. Short-Lived Auth Memory

If you are profiling multiple authorized pages, save auth material temporarily:

export LETHE_TOKEN='redacted-token-here'
export LETHE_COOKIE='session=redacted'

lethe auth save hackerone-prod \
  --bearer-token-env LETHE_TOKEN \
  --cookie-env LETHE_COOKIE \
  --header 'X-Program-Scope: authorized' \
  --ttl 30m

Reuse it:

lethe profile https://example.com/account --auth-ref hackerone-prod
lethe profile https://example.com/settings --auth-ref hackerone-prod

Manage saved auth:

lethe auth list
lethe auth clear hackerone-prod
lethe auth purge

The cache is local, temporary, and redacted in output. Keep TTLs short.

13. AI-Driven Planning

Lethe can use AI for planning, but the AI does not generate final payload strings. The AI only returns a safety verdict and strategy:

  • allow: normal authorized testing context.
  • review: scope or intent should be confirmed.
  • block: unsafe or abusive request.

Lethe still generates variants using deterministic local transformations.

Gemini Setup

Set the API key in your shell:

export GEMINI_API_KEY='your-gemini-key-here'

Add this to .lethe.toml:

[ai]
provider = "gemini"
model = "gemini-2.5-flash"
api_key_env = "GEMINI_API_KEY"

Run a plan:

lethe plan \
  --payload '<waf-test>' \
  --site-profile site-profile.json

Use AI planning during generation:

lethe generate \
  --payload '<waf-test>' \
  --site-profile site-profile.json \
  --ai

OpenAI Setup

export OPENAI_API_KEY='your-openai-key-here'

.lethe.toml:

[ai]
provider = "openai"
model = "gpt-4.1-mini"
api_key_env = "OPENAI_API_KEY"

Run:

lethe plan --payload '<waf-test>'

Claude / Anthropic Setup

export ANTHROPIC_API_KEY='your-anthropic-key-here'

.lethe.toml:

[ai]
provider = "claude"
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY"

You can also use provider = "anthropic" as an alias.

Run:

lethe plan --payload '<waf-test>'

Ollama Local Setup

Ollama is the easiest free/local option on Kali.

Install Ollama:

curl -fsSL https://ollama.com/install.sh | sh

Pull a model:

ollama pull llama3.2

.lethe.toml:

[ai]
provider = "ollama"
model = "llama3.2"

Run:

lethe plan --payload '<waf-test>'
lethe generate --payload '<waf-test>' --ai

No real API key is required for Ollama. Lethe uses the local OpenAI-compatible endpoint at http://localhost:11434/v1.

LM Studio Local Setup

Start LM Studio's local server, load a model, then use:

[ai]
provider = "lmstudio"
model = "local-model"

Default endpoint:

http://localhost:1234/v1

Aliases:

provider = "lm-studio"
provider = "lm_studio"

LocalAI Setup

Start LocalAI, make sure a model is available, then use:

[ai]
provider = "localai"
model = "llama-3.2-1b-instruct:q4_k_m"

Default endpoint:

http://localhost:8080/v1

Aliases:

provider = "local-ai"
provider = "local_ai"

OpenAI-Compatible Local Or Proxy Setup

Use this for local model servers or compatible gateways:

[ai]
provider = "openai-compatible"
model = "local-json-planner"
api_key_env = "OPENAI_API_KEY"
base_url = "http://localhost:11434/v1"

Important: openai-compatible requires base_url so Lethe does not accidentally send requests to the wrong endpoint.

14. AI Planning Without An API

For local testing or demos, use the included mock planner:

lethe plan \
  --payload 'a b' \
  --ai-command 'python examples/mock_ai_plan.py'

Use the mock plan during generation:

lethe generate \
  --payload 'a b' \
  --ai-plan-command 'python examples/mock_ai_plan.py'

15. HTTP Discrepancy Templates

Lethe can print safe request-shape templates for WAF/backend parser comparison. It does not send these requests.

lethe http-plan \
  --host example.com \
  --path /search \
  --param q=safe \
  --format raw

Include bounded local-lab stress templates:

lethe http-plan \
  --host example.com \
  --path /search \
  --include-stress \
  --max-padding 1024 \
  --regex-length 64 \
  --format markdown

Include HTTP/2 downgrade discrepancy templates for authorized proxy/WAF translation testing:

lethe http-plan \
  --host example.com \
  --path /search \
  --param q=safe \
  --include-http2 \
  --format raw

These are text templates only. They cover :path versus path, :authority versus host, duplicate pseudo-header rejection, lowercase-header enforcement, and TE/content-length downgrade consistency with harmless canaries.

Use stress templates only in owned labs or explicitly authorized environments.

16. The STYX CLI Signature

Project Lethe has a custom terminal signature:

STYX://PROJECT-LETHE [trace online]
canon.map=armed | mode=authorized-lab | output=clean
sig=Avinash K A//styxabhor

Force it:

lethe generate --payload '<test>' --banner

Disable it:

lethe generate --payload '<test>' --no-banner

The animated frames appear only in an interactive terminal:

STYX://PROJECT-LETHE [seed  ] <lethe.......................> canary indexed
STYX://PROJECT-LETHE [wash  ] <..lethe.....................> syntax rinsed
STYX://PROJECT-LETHE [morph ] <....lethe...................> layers braided
STYX://PROJECT-LETHE [trace ] <......lethe.................> canonical path
STYX://PROJECT-LETHE [online] <........lethe...............> trace online
STYX://PROJECT-LETHE [trace online]

17. Update Project Lethe

From inside the repo:

git pull
source .venv/bin/activate
pip install -e .

Run tests after updates:

PYTHONPATH=src python -m unittest discover -s tests

18. Troubleshooting

If lethe is not found:

source .venv/bin/activate
pip install -e .

If Python is too old:

python3 --version
sudo apt update
sudo apt install -y python3 python3-venv python3-pip

If AI planning says the API key was not found:

echo "$GEMINI_API_KEY"
echo "$OPENAI_API_KEY"
lethe config

If openai-compatible fails:

lethe config

Confirm ai_base_url is set.

If a site profile fails:

  • Confirm the URL starts with http:// or https://.
  • Confirm the route is in scope.
  • Confirm auth tokens or cookies are valid.
  • Try a higher timeout in .lethe.toml with profile_timeout = 20.

19. Safe Workflow Example

# 1. Profile an authorized page
lethe profile https://example.com/search --format json --output site-profile.json

# 2. Ask AI for a safety/context plan
lethe plan --payload '<waf-test>' --site-profile site-profile.json

# 3. Generate deterministic variants using that context
lethe generate --payload '<waf-test>' --site-profile site-profile.json --ai --limit 25

# 4. Explain one interesting transformation
lethe explain --payload '<waf-test>' --technique html_hex_entities --format markdown

# 5. Turn the transformation into report-ready analysis
lethe analyze --payload '<waf-test>' --technique html_hex_entities --format markdown

That is the clean Kali flow: profile, plan, generate, explain, analyze, report.