FACTION: turning a pen test into a report and a retest queue

An assessment workflow rather than a scanner

FACTION is described as your entire assessment workflow in a box. It does not scan anything. What it does is automate the reporting and review side of a penetration test: generating reports, peer reviewing them and tracking changes, handling custom DOCX templates for different assessment types and retests, managing assessment teams and tracking progress, tracking remediation with SLA warnings and alerts, and offering a full REST API for integration with other tools.

The repository is a Java project built with Maven, and the README places it under OWASP, which is also the headline in the repository description. It is now an OWASP project, with the project page linked from the readme.

There is also a version story you need to know before you start. The readme announces that OWASP Faction 2.0 has been released, that 2.0 is a major update, and that it will begin replacing this version. The 2.0 code lives in a separate repository, OWASP-Faction-2, and the section that follows is explicitly titled for the 1.x line.

So there are two questions to separate. Whether the workflow model fits an assessment team is answered in the documentation. Whether this particular branch is where you should build is not, since the author is steering new deployments toward the 2.0 repository.

Report templates and vulnerability templates are the core

Two template systems carry the weight of the reporting side.

The first is report templates. Custom DOCX templates can be created for different assessment types and for retests, and there is a separate documentation page on custom security report templates. The second is vulnerability templates, of which the feature list claims over 75 prepopulated. These are the finding descriptions that a consultant picks from, rather than retyping for every engagement.

Those vulnerability templates are not bundled in the repository image. The readme has a section titled Import the Vulnerability Templates with two steps: navigate to Templates then Default Vulnerabilities, and click Update from Faction. In other words the templates are fetched from the vendor's service after installation, which means an air-gapped instance cannot populate them without another route.

Around the templates sits the workflow. Screenshots in the readme show vulnerability templates, assessment scheduling, peer review with track changes, a remediation and retest queue, scheduled retests, an assessor retest interface and vulnerability status tracking. Custom report variables are listed as a separate feature, so the same template can be reused across engagements with different client names and dates.

Collaboration happens in the web app and in Burp

Real-time collaboration with assessors is offered through the web application and through Burp Suite Extensions, with the extension in its own repository, Faction-Burp. That is the design that makes sense for this tool: a tester records a finding in Burp, the finding lands in Faction, and the rest of the team works on it in the browser.

Peer review and change tracking are listed as headline capabilities, and the screenshots for those sections show a diff style view. For a consultancy where a second reviewer has to sign off before a report leaves the building, that is the reason to run this at all.

The extension model is broader than Burp. FACTION is described as extendable with custom plugins similar to Burp Extender, and version 1.2 introduced an App Store, described as making it easier for developers to extend Faction. Extensions can trigger custom code when events happen in the workflow, and the example given is sending all vulnerabilities to Jira when the assessment is complete, or updating a tracking system when a retest passes or fails.

Enterprise integration is also present: LDAP integration, OAuth 2.0 integration and SMTP integration, alongside the full REST API. That combination is what you need if the assessment data has to live inside an existing identity and ticketing estate rather than in a standalone tool.

Running it with Docker Compose

The stated requirements are a Java JDK 11 and Maven for building the project. MongoDB is optional for a VM deployment, with the caveat that it requires a CPU with AVX support, which is called out because people hit the problem on Oracle VirtualBox and on Kubernetes.

The quick setup builds the war file and deploys it to a container with three commands:

git clone [email protected]:factionsecurity/faction.git
cd faction
docker-compose up --build

Once the containers are up, you navigate to http://127.0.0.1:8080 to reach the instance, and on the first boot it asks you to create an admin account. That first boot step matters: the application has no default credentials, so the account you create at that prompt is the root of your instance.

The repository contains several compose files, which is how you can tell which one matches a deployment style: `docker-compose.yml` for the standard run, `docker-compose-dev.yml`, `docker-compose-hotreload.yml` and `docker-compose-official.yml`. There are matching Dockerfiles, a `Dockerfile.dev` and a `Dockerfile.dev-hotreload`, plus an `entrypoint.sh` and a `setenv.sh`. The project also has a `mise.toml` and a `.tool-versions` file, so the Java and Node versions are pinned somewhere.

The compose file ships default credentials

Here is the part to read twice before you deploy. The Mongo service is initialised with a fixed username and password, and the application container is handed a fixed encryption key:

    environment:
        - 'FACTION_REPORT_STORAGE=local'
        - 'FACTION_MONGO_HOST=faction-mongo'
        - 'FACTION_MONGO_DATABASE=faction'
        - 'FACTION_MONGO_USER=faction_mongo_user'
        - 'FACTION_MONGO_PASSWORD=faction_mongo_pass'
        - 'FACTION_MONGO_AUTH_DATABASE=admin'
        - 'FACTION_SECRET_KEY=faction_encryption_key'
        - 'FACTION_OAUTH_CALLBACK=http://localhost:8080'
        - 'FACTION_APPSTORE_ENABLED=true'

The password is `faction_mongo_pass` and the secret key is `faction_encryption_key`, both in plain text in the repository. A `FACTION_SECRET_KEY` is the kind of value you would expect to be protecting whatever it encrypts, so shipping a default one means that anyone who has read this repository knows the key of any instance that was deployed without changing it.

Other details in the same file are informative. `FACTION_REPORT_STORAGE=local` says where generated reports live. `FACTION_OAUTH_CALLBACK=http://localhost:8080` is the OAuth redirect and would need to change behind a real hostname. `FACTION_APPSTORE_ENABLED=true` turns the extension marketplace on. The Mongo data is bind-mounted from `~/.faction/data` so it survives container replacement, and the Mongo port is published on 27017 alongside the application on 8080.

None of this is unusual for a demo configuration, and the README is a demonstration setup. It just should not reach a network.

The container patches Tomcat before it starts

The Dockerfile shows exactly what the application expects. It starts from a Tomcat 9 image on JRE 11, and the first thing it does is patch the runtime configuration:

from tomcat:9-jre11 as base_app
RUN apt-get update
RUN apt-get upgrade -y
RUN apt-get install curl
RUN mkdir /opt/faction
#Fix issue with sending emails
RUN sed -i 's/^jdk.tls.disabledAlgorithms/# jdk.tls.disabledAlgorithms/' /opt/java/openjdk/conf/security/java.security
#Raise Tomcat's 2MB POST limit so large base64 image uploads work (25MB)
RUN sed -i 's/<Connector port="8080"/<Connector maxPostSize="26214400" port="8080"/' /usr/local/tomcat/conf/server.xml

Two changes are worth understanding. The first comments out the JDK disabled algorithms list, described in the comment as a fix for sending emails, which is a broad change to TLS behaviour that you would want to review rather than inherit. The second raises the connector POST limit from the Tomcat default of 2MB to 25MB, because screenshots are embedded as base64 in the payload.

The image then removes the default Tomcat webapps, including the manager, host-manager, docs, examples and ROOT, which is sensible hardening for an internet facing service, and downloads the application war from the project's latest release rather than copying a locally built one. The commented out COPY line is there for local builds, and the container entrypoint is the standard Tomcat catalina script.

GPL-2.0, an active release line and a hosted alternative

The licence is GPL-2.0 with the licence file at the root, and the repository is not archived. The last push was on 2026-10-03 and the recent tags are 1.8.12 on 2026-08-14, 1.8.13 on 2026-08-20 and 1.8.14 on 2026-10-03, so the 1.x line is still being shipped. The default branch is `main`, and the repository carries a `RELEASE_NOTES_1.8.6.md` file, a `SECURITY.md`, an `AGENTS.md` and a `.agents` directory.

If you would rather not run it yourself, the vendor offers hosting, and the readme makes a point of stating that instances are single tenant so you are not sharing infrastructure with untrusted parties. That is a reasonable answer for a consultancy that does not want to run Tomcat and Mongo itself, and it is also the reason the vendor maintains the template update endpoint and the App Store.

One structural thing deserves a flag. Sponsorship is part of the project, and the readme says sponsors get access to the Faction Discord server and will have bug reports prioritised. Paid access to a support channel on an open source OWASP project is a common arrangement, but it is worth knowing before you file issues expecting the same attention as a sponsor, and worth knowing if your organisation prefers contributions that are not routed through a paid tier.

For the 1.x line, the useful links are the manual and tutorials at docs.factionsecurity.com, the contributing guidelines, and the OWASP Slack channel #project-faction.

Editorial conclusion

FACTION suits a consultancy or security team that reviews each other's findings, retests findings over time, and needs consistent client-facing DOCX reports, especially one already using Burp Suite. It is a poor fit if you need to self host with care, because the shipped compose file carries default database passwords and a default encryption key that you must replace, and a poor fit for a new evaluation because the author intends 2.0 to replace this branch. Before deploying, read the environment variables in `docker-compose.yml`, set your own `FACTION_SECRET_KEY` and Mongo credentials, and check the OWASP-Faction-2 repository to see whether you should start there instead.

Frequently asked questions

Official sources

1. factionsecurity/faction on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases