Skip to content

About

Create findings in Gitlab using PenText and optional use of LLM

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

ROS Pentest Assistant

A local LLM-powered tool for creating issues and managing ROS Gitlab tasks.

App Screenshot

⚠️ 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.

Supported Models

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.

Configure the application

Both direct and Docker launches use the same .env file and validate the same core settings before starting. Create it once:

cp .env-sample .env

See .env file comments for what to fill in.

Quick start!

  1. Create a GitLab project access token for the configured project with:

    • Access level: Maintainer
    • Scopes: api, read_repository, and write_repository

    The application reads and writes repository files, creates pipelines, and may create the standard source/ files directly on main. 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. If main is 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.

  1. 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.

  2. When logged in to gitlab get the _oauth2_proxy and _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.

  3. 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.

  4. 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.

Configure the local LLM address

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.

Multiple projects

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.

Use a different environment file

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.sh

For 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.

Start the application

Direct Python launch

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.sh

The 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-unsafe

Docker launch

Use this when you want the application in a container. Before starting:

  1. Change LLM_HOST to host.docker.internal if the LLM runs on this same computer.
  2. Set PUID and PGID to the output of id -u and id -g. This lets Docker-created report files remain writable on the host.
  3. Leave FLASK_PORT=5000; set HOST_PORT only if port 5000 is already in use locally.

Then start it:

./start-docker.sh

The 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 down

Verify either launch

After signing in, open these endpoints in the browser or with authenticated requests:

  • /auth-status confirms GitLab authentication.
  • /health-check confirms GitLab and the local LLM are reachable.

Both should report success before creating or uploading findings.

Usage

  1. Access the application at http://127.0.0.1:<FLASK_PORT>/ (port 5000 by default)
  2. Recommended browser: Chromium

What can it do:

Quick Access Controls

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.

Core Features

1. Finding Management

  • Create Findings/Non-Findings using:
    • AI-powered LLM generation
    • Predefined templates from finding/non-finding database
    • Import .txt or .md finding drafts directly into the Finding form
    • Bulk import multiple .txt or .md finding 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.

2. Report Generation

  • Generate "Results in a Nutshell" summary from all findings
  • Auto-generate conclusions based on results summary
  • Add items to future work section

3. Report Management

The "Check Report" section offers:

  • XML Generation: Creates report.xml in 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.xml fields: ISO YYYY-MM-DD dates, 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.

4. Report Deployment

  • Automated report generation and upload
  • Configurable target directory in repository
  • Custom filename support

About

Create findings in Gitlab using PenText and optional use of LLM

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages