Running OWASP Faction¶

OWASP Faction ships as a set of Docker images that make up a complete install: the application, its database and object storage. Docker is the only thing the host needs. The images cover linux/amd64 and linux/arm64, so the same command works on an Apple Silicon Mac, an Intel laptop and a cloud server.

Install with one command¶

The installer checks the prerequisites, pulls the images, and writes a .env file with secrets generated by openssl rand -base64 48:

curl -fsSL https://raw.githubusercontent.com/factionsecurity/OWASP-Faction-2/main/install.sh | bash
cd owasp-faction-2
docker compose up -d

Then open http://localhost:8080 and sign in as admin with the password admin123.

Change the admin password first

The default credentials are seeded on first start and documented on this page, so anyone who can reach the install knows them. Change the password before you open the port to anyone else.

First start takes a few minutes. It runs every database migration and seeds the default roles, users and vulnerability categories.

Options¶

The installer reads four environment variables:

FACTION_DIR=/opt/faction \
FACTION_VERSION=2.0.1 \
HTTP_PORT=9000 \
PUBLIC_URL=https://faction.example.com \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/factionsecurity/OWASP-Faction-2/main/install.sh)"

Variable	What it sets
`FACTION_DIR`	Where the install lives. Defaults to `owasp-faction-2` in the current directory
`FACTION_VERSION`	The release to run. Defaults to `latest`, which tracks the newest full release and never a pre-release
`HTTP_PORT`	The port Faction listens on. Defaults to `8080`
`PUBLIC_URL`	The address users will reach Faction at, used in links in emails and notifications

The script starts nothing and writes only inside its install directory. Run it twice and it refuses to touch an existing .env, because regenerating the database password would lock a working install out of its own database.

Read the script first¶

Piping anything to bash means running code you have not read, and it is reasonable not to want to, particularly for a security tool. Download it, read it, then run it:

curl -fsSL -O https://raw.githubusercontent.com/factionsecurity/OWASP-Faction-2/main/install.sh
less install.sh
bash install.sh

Install by hand¶

The installer only does three things you can do yourself: fetch the compose file, create a .env with three secrets, and start the stack.

curl -LO https://raw.githubusercontent.com/factionsecurity/OWASP-Faction-2/main/docker-compose.yml
curl -LO https://raw.githubusercontent.com/factionsecurity/OWASP-Faction-2/main/.env.example
cp .env.example .env

Open .env and set JWT_SECRET, DATABASE_PASSWORD and STORAGE_SECRET_KEY to long random values, then:

docker compose up -d

Upgrading¶

docker compose pull && docker compose up -d

A plain docker compose restart does not upgrade anything. It reuses the images already on disk, and pull is the step that fetches the new release.

.env pins FACTION_VERSION=latest. Set it to a version to control when you move. Published tags carry no v, so the release tagged v2.1.0 is FACTION_VERSION=2.1.0.

Check what you are running with:

curl http://localhost:8080/api/v1/status

The version is also shown at the bottom right of the UI.

Putting it in front of users¶

Faction serves plain HTTP. Put it behind a reverse proxy that terminates TLS before exposing it beyond a private network, and set PUBLIC_URL to the address the proxy answers on so that links in emails point at the right place.

What the open source edition includes¶

Everything in this documentation is part of OWASP Faction unless it says otherwise. The edition applies a few limits: one AI provider, four AI prompts and two installed extensions. Users are not capped.

Some capabilities live only in the commercial edition Faction Security builds on the same codebase: single sign-on, white-labelling, inbound email threading, prompt-level AI audit logging, encrypted PDFs, an external owner portal and custom roles. In the interface these appear marked with a ◆ rather than hidden, so a feature you cannot find is explained rather than mysterious.

Building from source¶

If you want to change Faction rather than run it, the repository README covers the toolchain, Java 25, Node.js 20 and Maven, and the development workflow.

Next: Schedule an assessment.