## 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](https://github.com/hahwul/dalfox/tree/v2) and continues to receive security backports. See [SECURITY.md](./.github/SECURITY.md) for the support policy, and the [migration guide](https://dalfox.hahwul.com/getting-started/migration/) 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](https://dalfox.hahwul.com/getting-started/installation/) 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](https://dalfox.hahwul.com/getting-started/installation/) for details. Prebuilt binaries (including statically-linked musl variants for Linux) are available on the [GitHub Releases](https://github.com/hahwul/dalfox/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](https://dalfox.hahwul.com/reference/cli/) and [Quick start](https://dalfox.hahwul.com/getting-started/quick-start/) documents for more examples. ## Contributing if you want to contribute to this project, please see [CONTRIBUTING.md](https://github.com/hahwul/dalfox/blob/main/.github/CONTRIBUTING.md) and Pull-Request with cool your contents. [](https://github.com/hahwul/dalfox/graphs/contributors) ## About the Name The name comes from 'Dal' ([달](https://en.wiktionary.org/wiki/달)) 🌙, 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**](https://gitter.im/amberframework/amber) for quick questions. * [**Stack Overflow**](https://stackoverflow.com/questions/tagged/amber-framework) for questions about the Crystal Language and Amber Framework. * [**Github**](https://github.com/amberframework/amber) for getting acquainted with source code, current issues and progress. * [**Online Guides**](https://docs.amberframework.org/amber) for getting down and dirty working with Amber. * [**Twitter**](https://twitter.com/amberframework) 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!](https://github.com/amberframework/amber/blob/master/.github/CONTRIBUTING.md) ## 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](guides/). If you want a step by step tutorial try the [quick start](getting-started/). 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](http://kemalcr.com/cookbook/hello_world/) by [@sdogruyol](https://github.com/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. ``` 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 on`ApplicationController`, 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 ```