dalfox Documentation

Dalfox is a powerful open-source XSS scanner and utility focused on automation.

5,214 stars Rust Rust 1 file Β· ~3,829 tokens #bugbounty#bugbounty-tool#devsecops#hacktoberfest#rust#security#xss#xss-scanner
RAW Doc

1. Project Overview & Quickstart (hahwul/dalfox)

Looking for the Go (v2.x) version? Dalfox v3 is a complete rewrite in Rust. The Go codebase is preserved on the v2 branch and continues to receive security backports. See SECURITY.md for the support policy, and the migration guide for what changed in v3.

Dalfox is a powerful open-source tool that focuses on automation, making it ideal for quickly scanning for XSS flaws and analyzing parameters. Its advanced testing engine and niche features are designed to streamline the process of detecting and verifying vulnerabilities.

Key features

  • Subcommands: scan (URL / file / pipe / raw-HTTP, auto-detected), server, payload, mcp
  • Discovery: Parameter analysis, static analysis, BAV testing, parameter mining
  • XSS Scanning: Reflected, Stored (SXSS), DOM-based, with optimization and DOM/AST verification
  • WAF: Fingerprinting with confidence scoring, bypass tracking, and tunable --waf-min-confidence
  • HTTP Options: Custom headers, cookies, methods, proxy, and more
  • Output: JSON/JSONL/Plain/Markdown/SARIF/TOML formats, silence mode, detailed reports
  • Extensibility: REST API, MCP stdio server, custom payloads, remote wordlists

And the various options required for the testing :D

Installation

Homebrew (macOS/Linux)

bash
brew install dalfox

# https://formulae.brew.sh/formula/dalfox

Snapcraft (Ubuntu)

bash
sudo snap install dalfox

Arch Linux (AUR)

bash
yay -S dalfox
# or
paru -S dalfox

See the Installation guide for manual build instructions.

Nixpkgs (NixOS)

A package is available for Nix or NixOS users. Keep in mind that the latest releases might only
be present in the unstable channel.

bash
nix-shell -p dalfox

Nix Flakes

For Nix users with flakes enabled:

bash
# Run directly
nix run github:hahwul/dalfox -- scan https://example.com

# Install
nix profile install github:hahwul/dalfox

# Development environment
nix develop github:hahwul/dalfox

See Installation guide for details.

Prebuilt binaries (including statically-linked musl variants for Linux) are available on the GitHub Releases page.

Usage

bash
dalfox [mode] [target] [flags]
  • Single URL: dalfox scan http://example.com -b https://callback
  • File Mode: dalfox scan urls.txt --custom-payload mypayloads.txt
  • Pipeline: cat urls.txt | dalfox scan --headers "AuthToken: xxx"
  • Custom injection point (query): dalfox scan 'https://example.com/?q=FUZZ&page=1' --inject-marker FUZZ
  • Custom injection point (header): dalfox scan https://example.com -H 'X-Search: FUZZ' --inject-marker FUZZ

Check the CLI reference and Quick start documents for more examples.

Contributing

if you want to contribute to this project, please see CONTRIBUTING.md and Pull-Request with cool your contents.

About the Name

The name comes from 'Dal' (달) πŸŒ™, the Korean word for 'moon', combined with 'Fox' 🦊.

2. Official Technical Reference & Guides (hahwul/docs)

File: README.md

Introduction

Amber is a web development framework written in the Crystal programming language. The framework implements the server-side MVC pattern using the object-oriented paradigm. Many of Amber's components and concepts will be familiar for developers with experience with other web frameworks like Phoenix, Ruby on Rails or Python's Django.

Amber aims to deliver developer happiness, productivity, and bare metal performance. The Crystal language is heavily inspired by Ruby, delivering familiarity, productivity, and a low learning curve for experienced Ruby developers. Meanwhile, Crystal also has some modern features like macros, first class concurrency, union types, C bindings, and a built in dependency manager. Amber takes advantage of all these features providing you an opinionated structure to develop a web application.

Amber offers a variety of familiar tools such as generators, database management, CLI, deployment tools, docker support, encrypted secrets, websockets, and more for fast prototyping and developing enterprise-grade web applications. If you come from a Ruby on Rails background you will feel right at home, but, be aware Amber is not Rails! Amber is type-safe, compiled, and embraces the best features from many different frameworks for example pipes for routing which is more similar to the Phoenix framework.

The aim of this introductory guide is to present a high-level overview of Amber Framework and the layers underneath that support it.

Getting Help

If you’re stuck, there are a number of places you can get help.

  • Gitter for quick questions.
  • Stack Overflow for questions about the Crystal Language and Amber Framework.
  • Github for getting acquainted with source code, current issues and progress.
  • Online Guides for getting down and dirty working with Amber.
  • Twitter to see latest news and announcements about Amber Framework.

Contributing

Contributing to Amber can be a rewarding way to learn, teach, and build experience in just about any skill you can imagine. You don’t have to become a lifelong contributor to enjoy participating in Amber.

Amber is a community effort and we want You to be part of ours Join Amber Community!

First Steps

Learning a new framework can be intimidating and exciting at the same time. To help you along, we have created a cookbook packed with examples and recipes to get the common tasks completed.

If you are new, you should start off with the guides.

If you want a step by step tutorial try the quick start.

Happy developing!

File: cli/README.md

CLI

Amber has a built in CLI tool, to make your life easier while developing applications.

Here is a list of the available commands:

  • db, database - Performs database maintenance tasks
  • e, encrypt - Encrypts environment YAML file. [env | -e --editor | --noedit]
  • x, exec - Executes Crystal code within the application scope
  • g, generate - Generate Amber classes
  • n, new - Generates a new Amber project
  • routes - Prints all defined application routes
  • w, watch - Starts amber development server and rebuilds on file changes

Read a long this guide to learn more about these command and how much time and efficient it can make your development experience.

Getting Command Help

You can get help from each command by running -h or --help next to the command

Eg.

text
$ amber --help

This will output to your shell the following documentation.

text
amber [OPTIONS] SUBCOMMAND

Amber - Command Line Interface

  The `amber new` command creates a new Amber application with a default
  directory structure and configuration at the path you specify.

  You can specify extra command-line arguments to be used every time
  `amber new` runs in the .amber.yml configuration file in your project
  root directory

  Note that the arguments specified in the .amber.yml file does not affect the
  defaults values shown above in this help message.

  Usage:
  amber new [app_name] -d [pg | mysql | sqlite] -t [slang | ecr] -m [granite, crecto] --deps

Subcommands:
  db, database  # Performs database maintenance tasks
  e, encrypt    # Encrypts environment YAML file. [env | -e --editor | --noedit]
  x, exec       # Executes Crystal code within the application scope
  g, generate   # Generate Amber classes
  n, new        # Generates a new Amber project
  routes        # Prints all defined application routes
  w, watch      # Starts amber development server and rebuilds on file changes

Options:
  -d, --database  # Preconfigure for selected database. Options: pg | mysql | sqlite (default: pg)
  -m, --model     # Preconfigure for selected model. Options: granite (default: granite)
  -t, --template  # Preconfigure for selected template engine. Options: slang | ecr (default: slang)
  -h, --help      # Describe available commands and usages
  -v, --version   # Prints Amber version

Example:
  amber new ~/Code/Projects/weblog
  This generates a skeletal Amber installation in ~/Code/Projects/weblog.

Usage

bash
amber new [your_app] -d [pg | mysql | sqlite] -t [slang | ecr] --deps
cd [your_app]

Options

  • -d defaults to pg
  • -t defaults to slang
  • --deps will run crystal deps for you.

File: cookbook/README.md

Cookbook

This Amber Cookbook is inspired by original Kemal Cookbook by @sdogruyol

{% page-ref page="from-scratch.md" %}

{% page-ref page="hello-world.md" %}

{% page-ref page="cors.md" %}

{% page-ref page="file-download.md" %}

{% page-ref page="file-upload.md" %}

{% page-ref page="authenticate.md" %}

{% page-ref page="json-api.md" %}

{% page-ref page="json-mapping.md" %}

{% page-ref page="websocket-chat.md" %}

File: deployment/README.md

Deployment

{% hint style="info" %}
This section contain guides for deploying amber projects to Digital Ocean and Heroku
{% endhint %}

{% hint style="warning" %}
Guides for other platforms like Amazon Web Services (AWS), Google Compute Engine (GCE) and Azure are work in progress...
{% endhint %}

{% page-ref page="manual-deploy.md" %}

{% page-ref page="digital-ocean.md" %}

{% page-ref page="heroku.md" %}

{% page-ref page="dokku.md" %}

File: examples/README.md

Examples

{% page-ref page="amber-auth.md" %}

{% page-ref page="crystal-debug.md" %}

{% page-ref page="json-api-full-crud.md" %}

{% page-ref page="minimal-configuration.md" %}

File: guides/controllers/cookies.md

Cookies

Cookies are read and written through Amber::Base::Controller#cookies.

The cookies being read are the ones received along with the request, the cookies being written will be sent out with the response. Reading a cookie does not get the cookie object itself back, just the value it holds.

It's advisable that you only store simple data (strings and numbers) in cookies. If you have to store complex objects, you would need to handle the conversion manually when reading the values on subsequent requests.

Amber also has an encrypted cookie jar for storing sensitive data. The encrypted cookie jar encrypts the values in addition to signing them, so that they cannot be read by the end user.

Examples of writing

ruby
class CommentsController < ApplicationController
  def new
    # Auto-fill the commenter's name if it has been stored in a cookie
    @comment = Comment.new(author: cookies[:commenter_name])
  end

  def create
    @comment = Comment.new(params[:comment])
    if @comment.save
      flash[:notice] = "Thanks for your comment!"
      if params[:remember_name]
        # Remember the commenter's name.
        cookies[:commenter_name] = @comment.author
      else
        # Delete cookie for the commenter's name cookie, if any.
        cookies.delete(:commenter_name)
      end
      redirect_to @comment.article
    else
      render action: "new"
    end
  end
end

Examples of reading

ruby
cookies[:user_name]           # => "david"
cookies.size                  # => 2
JSON.parse(cookies[:lat_lon]) # => [47.68, -122.37]
cookies.encrypted[:discount]  # => 45

Please note that if you specify a :domain when setting a cookie, you must also specify the domain when deleting the cookie:

ruby
cookies.set "name", "a yummy cookie", expires: 1.year.from_now, domain:  "domain.com"
cookies.delete "name", domain: "domain.com"

The optional parameters for setting cookies are:

ruby
path   # The path for which this cookie applies. Defaults to the root of the application.
domain # The domain for which this cookie applies so you can restrict to the domain level. 
        # If you use a schema like www.example.com and want to share session with user.example.com 
        # set :domain to :all. Make sure to specify the :domain option with :all or Array again 
        #  when deleting cookies.

domain: nil                           # Does not set cookie domain. (default)
domain: :all                          # Allow the cookie for the top most level domain and subdomains.
domain: %w(.example.com .example.org) # Allow the cookie for concrete domain names.

tld_length # When using :domain => :all, this option can be used to explicitly set the TLD length 
            # when using a short (<= 3 character) domain that is being interpreted as part of a TLD. 
            # For example, to share cookies between user1.lvh.me and user2.lvh.me, set :tld_length to 1.

expires    # The time at which this cookie expires, as a Time object.
secure     # Whether this cookie is only transmitted to HTTPS servers. Default is false.
httponly   # Whether this cookie is accessible via scripting or only HTTP. Defaults to false.

File: guides/controllers/csrf.md

CSRF

To use CSRF, enable the pipe in your routes.cr by adding the following pipe to a pipeline.

text
plug Amber::Pipe::CSRF.new

Then, insert the csrf_tag helper in your forms.

How to use CSRF with AJAX

Simply call the csrf_tag helper inside your controller and return it as part of a JSON object:

ruby
def my_action
    {csrf: csrf_tag}.to_json
end

In your Javascript, after getting the JSON object back, refresh your CSRF tag with the one from the server.

javascript
$("input[name*=_csrf]").replaceWith(e['csrf']);

File: guides/controllers/filters.md

Filters

Filters are methods that are run "before", "after" or "around" a controller action.

Filters are inherited, so if you set a filter onApplicationController, it will be run on every controller in your application.

Before filter

"before" filters may halt the request cycle. A common "before" filter is one which requires that a user is logged in for an action to be run. You can define the filter method this way:

ruby
# Filters are methods that are run "before", "after" a controller action.
before_action do
  # runs for specified actions
  only [:index, :world, :show] { increment(1) }
  # runs for all actions
  all { increment(1) }
end

After filter

"after" filters are executed after the request cycle. A common "after" filter is one which requires to cleanup user data after an action has been run. You can define the filter method this way:

ruby
after_action do
  # runs for specified actions
  only [:index, :world] { increment(1) }
end

Explore Related Technologies & Topics

View All 9,111+ Repositories β†’

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#bugbounty Browse bugbounty catalog β†’ #bugbounty-tool Browse bugbounty-tool catalog β†’ #devsecops Browse devsecops catalog β†’ #hacktoberfest Browse hacktoberfest catalog β†’ #rust Browse rust catalog β†’ #security Browse security catalog β†’ ⚑ MCP Servers Model Context Protocol β†’ 🧠 Agent Skills Prompt & rule files β†’ πŸ”Œ OpenAPI Specs REST & Swagger schemas β†’