A local LLM-powered tool for creating issues and managing ROS Gitlab tasks.
⚠️ Important: This tool is designed to work with local LLMs only. Do not use external LLM services as this would expose sensitive information to third parties.
Any local OpenAI API-compatible backend works, including Ollama, llama.cpp, and vLLM. Do not configure an external LLM service: report content can contain sensitive assessment data.
Both direct and Docker launches use the same .env file and validate the same
core settings before starting. Create it once:
cp .env-sample .envSee .env file comments for what to fill in.
-
Create a GitLab project access token for the configured project with:
- Access level: Maintainer
- Scopes:
api,read_repository, andwrite_repository
The application reads and writes repository files, creates pipelines, and may create the standard
source/files directly onmain. Token scopes do not override the GitLab project role: a Guest token can authenticate and read issue metadata, but cannot access the repository or run this workflow. Ifmainis protected, its branch rule must also allow Maintainers to push and merge.
You could also use the CI token but ideally just create your own and set a expiration date.
-
Find projectid next to fork button (start, fork, 3 dots) by clicking on 3 dots. in the project you want to work in. And add to the env file together with the project access token.
-
When logged in to gitlab get the
_oauth2_proxyand_gitlab_session. Those cookies are required otherwise we can't access through keycloak and gitlab using the tool. If there is a way in the future we can just use a special token for this then we will change this. It's not pretty but it works. Note that you have to change these usually next time when you run this tool again. -
So with all of this you should be able to load up the app with ./start-local.sh (which is fully tested) or start-local.sh (which should work but not tested lately). So in case of issues make a PR.
-
In case the tool does not work check you browser dev tools network and console for what the issue is. And also the console of that is shown when running the start script.
LLM_HOST should normally be the complete OpenAI-compatible endpoint, for
example http://127.0.0.1:11434/v1/chat/completions. A bare server URL or a
/v1 URL is also accepted and normalized automatically. Health checks probe
the corresponding models endpoint when available.
The correct hostname depends on how you start the app:
| LLM location | Direct launch | Docker launch |
|---|---|---|
| LLM runs on the same computer | http://127.0.0.1:11434/v1/chat/completions |
http://host.docker.internal:11434/v1/chat/completions |
| LLM runs on another LAN machine | Use its reachable private IP address | Use the same reachable private IP address |
Do not use 127.0.0.1 for a host-based LLM from Docker: inside the container,
it means the container itself. The supplied Compose configuration maps
host.docker.internal to the Docker host.
On Linux, that hostname reaches Docker's host gateway rather than the host's
loopback interface. If your LLM listens only on 127.0.0.1 (a common default),
configure it to listen on an address reachable from Docker before using this
URL. Restrict that address with a host firewall so the LLM is not exposed to
untrusted networks.
The first project uses NAME, PROJECT_ID, and PRIVATE_TOKEN. Optional
additional projects use contiguous numeric suffixes: NAME2, PROJECT_ID2,
PRIVATE_TOKEN2, then NAME3, and so on. The selected project is stored only
as an index in the browser session; IDs and credentials remain server-side.
Pass a path via ENV_FILE for either launch mode:
ENV_FILE=/path/to/project.env ./start-local.sh
ENV_FILE=/path/to/project.env ./start-docker.shFor Docker, keep a custom environment file outside the repository/build context. The launcher reads it on the host and Compose injects its values into the container; it is not copied into the image.
Set LOG_FINDING_REQUEST_DETAILS=false (the default) to keep finding-creation
diagnostics off. When enabled, it records safe metadata only, never request
bodies or header values.
Use this when the app and local LLM run directly on your workstation. Leave
LLM_HOST set to the 127.0.0.1 form shown above, then run:
./start-local.shThe script creates or updates venv, installs requirements, and starts the
same app.py entrypoint used by Docker. Open
http://127.0.0.1:<FLASK_PORT>/ (port 5000 by default) and sign in with
USER_ADMIN and PASSWORD_ADMIN.
For HTTP request/response tracing while debugging startup/runtime issues:
# Safe mode (redacts sensitive values in logs)
./start-local.sh --trace-http
# Full raw mode (prints secrets; use only in secure local troubleshooting)
./start-local.sh --trace-http-unsafeUse this when you want the application in a container. Before starting:
- Change
LLM_HOSTtohost.docker.internalif the LLM runs on this same computer. - Set
PUIDandPGIDto the output ofid -uandid -g. This lets Docker-created report files remain writable on the host. - Leave
FLASK_PORT=5000; setHOST_PORTonly if port 5000 is already in use locally.
Then start it:
./start-docker.shThe application is available at http://127.0.0.1 on the configured
HOST_PORT (port 5000 by default). Useful lifecycle commands are:
docker compose logs -f pentext-assistant
docker compose downAfter signing in, open these endpoints in the browser or with authenticated requests:
/auth-statusconfirms GitLab authentication./health-checkconfirms GitLab and the local LLM are reachable.
Both should report success before creating or uploading findings.
- Access the application at
http://127.0.0.1:<FLASK_PORT>/(port 5000 by default) - Recommended browser: Chromium
Located in the top-right corner:
- 💻 Computer icon: Toggles health checks
- 📁 Folder icon: Project switcher (configurable via .env)
PDF passwords remain in the approved secret-delivery channel and are not retrieved by the browser.
- Create Findings/Non-Findings using:
- AI-powered LLM generation
- Predefined templates from finding/non-finding database
- Import
.txtor.mdfinding drafts directly into the Finding form - Bulk import multiple
.txtor.mdfinding drafts straight into the issue tracker - Import existing XML files (useful for retesting)
- Interactive Text Enhancement:
- 🔄 Refresh icon to regenerate content
- Select text for LLM-based improvements
- Natural language queries (e.g., "Explain why RCE is bad")
- Direct repository integration for saving findings
Finding import format:
Title: Example Finding Title
ThreatLevel: High
Type: Example Finding Type
RetestStatus: unresolved
## Short Description
One concise paragraph describing the finding.
## Technical Description
Detailed technical evidence, affected endpoints, proof, and reproduction notes.
## Impact
Clear business and technical impact.
## Recommendation
Concrete remediation guidance.
## Update
Optional retest or follow-up notes.
- Generate "Results in a Nutshell" summary from all findings
- Auto-generate conclusions based on results summary
- Add items to future work section
The "Check Report" section offers:
- XML Generation: Creates
report.xmlin the repository - Completeness Check: Validates report structure and content. For supported missing details, the result includes a guided form that writes the values back to the correct
report.xmlfields: ISOYYYY-MM-DDdates, pentester name and bio, version author, project-management scope, and one or more reconnaissance tool title/URL pairs. The form re-checks the report after saving; any unrelated validation issues remain visible. - Format Conversion:
- Converts issues to XML format
- Automatic image size optimization
- Comprehensive Review:
- Report completeness verification
- Automated corrections (whitespace, punctuation)
- Length optimization for recommendations and impacts
- Quality assessment of:
- Findings and non-findings
- Risk assessments
- Conclusions
- Future work items
Review options:
- Individual issue review
- Batch review (process all issues at once)
- Choice between original and LLM-enhanced versions
- Direct repository updates
Note: While the LLM provides helpful suggestions, human verification is essential. The pentester remains responsible for report quality and accuracy.
- Automated report generation and upload
- Configurable target directory in repository
- Custom filename support
