Working with AI agents
Ask an AI assistant about ScanSuite, let a coding agent install and run it, and give it the ScanSuite skill to scan and read results.
An AI assistant or coding agent can work with ScanSuite in three ways. It can answer questions about ScanSuite from this documentation; it can install and administer a ScanSuite server by following the documentation, stopping wherever a person has to act; and, with the ScanSuite skill, it can run scans and read their results.
Paste this line into Claude Code, Codex, Copilot, Cursor or another coding agent. It installs the ScanSuite skill and connects it to your server, and stops for the steps only you can do.
Set up ScanSuite for me: fetch and follow https://scansuite.eu/documentation/agent-setup.md| What you want | What you use | What it needs |
|---|---|---|
| Ask about ScanSuite | Point any assistant at the documentation. | Nothing. |
| Let an agent install and administer it | A coding agent with a shell on the server, such as Claude Code. | The documentation pages; you do the steps marked as a person's. |
| Let an agent scan | A coding agent with the ScanSuite skill. | A team API token in a file the agent reads. |
Ask about ScanSuite
Every documentation page is also available as Markdown, which assistants read more reliably than HTML:
| Source | What it holds | Use it when |
|---|---|---|
| https://scansuite.eu/documentation/llms.txt | An index: what ScanSuite is, the standard tasks with the page for each, and every page as a Markdown link with a one-line summary. | Give it to an assistant that can fetch pages; it reads only what it needs. |
| https://scansuite.eu/documentation/llms-full.txt | Every page in one file, in sidebar order. | An assistant that cannot browse: upload or paste the whole file. |
| Any page URL with .md appended | That page as Markdown, for example https://scansuite.eu/documentation/reference/cicd.md. | A question about one task. |
| Copy for AI (at the top of every page) | Copies the page's Markdown to the clipboard. | Pasting one page into a chat. |
Example prompts:
Read https://scansuite.eu/documentation/llms.txt and tell me whether ScanSuite can scan a Java
Spring service and its Terraform, what it would find, and which parts need an AI provider.
Using https://scansuite.eu/documentation/llms.txt, compare what ScanSuite runs on a merge request
with what it runs nightly, and say how long each takes and what it costs in AI.
Read https://scansuite.eu/documentation/installation/technical-requirements.md and tell me whether
a server with 8 CPU cores, 32 GB of memory and 200 GB of disk is enough for the full scanner set.Let an agent install and administer it
A coding agent with a shell on the target server (Claude Code, for example) can follow the installation and administration pages step by step. Give it the page for the task, not your credentials.
| Task | Page to give the agent |
|---|---|
| Check a server before installing | Technical Requirements |
| Install on a Linux server | Install ScanSuite Teams |
| Install on Google Cloud or Azure | Install on Google Cloud, Install on Microsoft Azure |
| Replace the certificate | SSL/TLS Setup |
| Something does not work | Troubleshooting |
| Back up and restore | Backup and restore |
| From a fresh server to a first report | Quick start |
Where the agent stops
In the Markdown version of every page, a step that only a person can do starts with A person does this step:. An agent does everything around such a step itself and asks you only for what only you can give: where a file is, a password typed at a program's own prompt in a terminal it opens for you, a DNS change, a sign-in or an approval. It does not ask you to move files or run commands it can run itself. Never paste a licence code, password, token or private key into the chat: you enter each secret where the page says, in your own terminal or in the ScanSuite console. These steps are always a person's:
- saying where the licence file is, and typing the registry password at the installer's prompt;
- DNS records and replacing the TLS certificate;
- creating the first account at
https://<YOUR_DOMAIN>/setup, and every sign-in; - issuing API tokens and typing any secret;
- approving a change to a production server, including
terraform apply; - confirming that you are authorised to test a target, and allowing targets for the team.
What an agent can do on its own
Most administration happens in the console, which needs a person signed in. What an agent can do without one, and what stays with a person:
| Task | An agent can | A person does |
|---|---|---|
| Install, update, check | Check the host against the requirements, copy the licence file into place, start the installer in a terminal you can type into, and run ./scansuite update --yes, doctor, status, version and logs. On Google Cloud and Azure: fill in terraform.tfvars and run terraform plan. | Saying where the licence file is, typing the registry password at the installer's prompt, DNS, the certificate, the first account at /setup, terraform apply. |
| Teams, members, service accounts, tokens | Nothing: these need a person signed in. | All of it, on the Teams page and in System Settings. |
| Team settings: allowed targets, AI, Team SSH key, integrations | Nothing. | All of it, on the Teams page. |
| Products | Create and rename through the team API, or let a pipeline create them (scansuite-ci --create-product). | Deleting a product. |
| Scans: static, web, infrastructure, AI pentest | Start, follow, cancel and read them with scansuite-ci or the team API. | Allowing the targets; confirming authorisation to test them. |
| Schedules | A schedule in the CI system (a GitLab pipeline schedule, cron) that runs scansuite-ci. | Schedules on the ScanSuite Schedules page. |
| Triage | Read findings and secrets; change a finding's status, notes and owner, with a token that has Change findings (Custom preset). | Suppression rules, Suppress by name, actions on a selection, exports from the Vulnerabilities page. |
| Assets | Read, add, change and delete through the team API, with the asset permissions. | — |
| Backup and restore | ./scansuite backup db, ./scansuite restore db FILE --yes; SCANSUITE_BACKUP_PASSWORD opens a password-protected archive. | backup secrets and backup db --encrypt print a password once: a person runs them. Storing archives off the host. |
Example prompts:
Install ScanSuite Teams on this server by following
https://scansuite.eu/documentation/installation/install-scansuite-server. Check the technical
requirements first and show me what you found. Do the work yourself: ask me where the licence file
is and copy it into place, and start the installer in a terminal I can type into, so that I only type
the registry password when it asks. Never ask me to paste a licence code or a password into this chat.Create one ScanSuite product per repository listed in repos.txt, through the team API, following
https://scansuite.eu/documentation/usage/products. SCANSUITE_URL and SCANSUITE_TEAM are set; read
the token from ~/.scansuite-token and never print it. Skip products that already exist and show me
what you created.Run an AI SAST scan of this repository into the product shop-api with the ScanSuite skill, following
https://scansuite.eu/documentation/reference/agent-skill. Turn the quality gate off, then summarise
the Critical and High findings with their file.Add a nightly cron entry on this server that backs up the ScanSuite databases, following
https://scansuite.eu/documentation/administration/backup-and-restore. Do not use --encrypt in cron:
it prints the archive password into the log. Show me the entry before you install it, and tell me
where the archives go so I can copy them off the host.Let an agent scan
ScanSuite ships an agent skill: a small package that teaches an AI coding assistant to run ScanSuite scans and read the results. Ask it to "scan this repository" or "find what's exposed for example.com", and it picks the scan, runs it through the ScanSuite client, waits, and reports what matters. The skill uses the open SKILL.md format that Claude, OpenAI Codex and GitHub Copilot all load, and is published in the public repository github.com/cepxeo/scansuite-ci.
The skill uses the team API, which is part of ScanSuite Teams.
It runs static analysis of code (AI SAST, classic SAST, secrets, dependencies, IaC), dynamic scans of web applications, and infrastructure scans (network discovery, OSINT and subdomains, Nuclei, OpenVAS or Nessus where set up, container-image CVEs, the AI pentest); it chains them, for example an OSINT sweep of a domain followed by a port scan of the hosts it finds; and it reads findings, secrets, logs and reports. With the right token it also triages findings.
Install the ScanSuite skill from github.com/cepxeo/scansuite-ci by following
https://scansuite.eu/documentation/reference/agent-skill, run its preflight, then scan this
repository and summarise what matters. Stop at every step marked "A person does this step";
never ask me for the token, which is in ~/.scansuite-token.Before you start
| You need | How to check |
|---|---|
| A team on a ScanSuite Teams server, and the Team admin role to issue a token | The Teams page says Your role in this team: Team admin. |
| bash, curl and python3 on the machine the agent runs on | bash --version; curl --version; python3 --version |
| Docker, or the Python client | docker --version. Without Docker the skill downloads the client your server publishes and checks its checksum, or uses the file SCANSUITE_CLIENT names. |
| For DAST and infrastructure scans: the targets allowed for the team | Teams page, Scanning tab, Check whether targets are allowed. |
| For AI scans: an AI provider for the team | The preflight below does not mark mlsast NOT AVAILABLE. |
On Windows, run the agent in WSL or Git Bash; with Git Bash set MSYS_NO_PATHCONV=1 so Docker paths are passed unchanged.
Give it a token
- 01Create a service account
Teams page, People tab, Automation and API tokens: under New service account give it a name such as agent, set Role to Operator and select Create.
- 02Issue a token
New token on that account. CI pipeline lets the agent scan and read results. To let it triage findings and read hosts and ports, choose Custom and tick the CI pipeline permissions plus Change findings and write proof-of-concept exploits and See assets. Select Create token, and note the team name the dialog shows.
Save the token to a file only you can read. Run this in your own terminal, paste the token when it waits, and press Enter; the token is not shown and does not enter your shell history:
umask 077; read -rs SST && printf '%s' "$SST" > ~/.scansuite-token; unset SSTThe skill reads the token from this file and never puts it in the chat or on a command line it shows. Do not paste the token into the conversation.
| Variable the skill reads | Default | What it is |
|---|---|---|
| SCANSUITE_URL | — | Your ScanSuite address, for example https://scansuite.example.com. |
| SCANSUITE_TEAM | — | The team name the Automation and API tokens card and the new-token dialog show. |
| SCANSUITE_TOKEN_FILE | ~/.scansuite-token | Another file that holds the token. |
| SCANSUITE_CLIENT | the Docker image appsec4u/scansuite-ci:1 | A path to scansuite-ci.py, to run the client without Docker. |
Tell the agent SCANSUITE_URL and SCANSUITE_TEAM, or answer when it asks.
Treat the token as a credential: anyone who can read ~/.scansuite-token can scan as that service account. Revoke it on the Teams page when the agent no longer needs it.
Install it in your assistant
A skill is a folder containing a SKILL.md file. Each tool loads it from its own location, so the install is "put the folder where the tool looks". In the repository the skill lives at plugins/scansuite/skills/scansuite/: copy that folder.
Claude Code
The repository is also a Claude Code plugin marketplace, so you can install without copying files. In a Claude Code session:
/plugin marketplace add cepxeo/scansuite-ci
/plugin install scansuite@scansuite-ciOr copy the folder into a skills directory: ~/.claude/skills/ for every project, or .claude/skills/ inside one repository:
git clone https://github.com/cepxeo/scansuite-ci
cp -r scansuite-ci/plugins/scansuite/skills/scansuite ~/.claude/skills/scansuiteClaude (claude.ai and the desktop app)
Open Settings → Customize → Skills and upload the skill as a .zip whose contents are the scansuite/ folder (so the archive holds scansuite/SKILL.md). It syncs to your account across claude.ai, the desktop app and Claude Code. Scans need a shell, so run them from Claude Code or the desktop app with a terminal.
OpenAI Codex
Codex reads skills from .agents/skills/ in your project and from ~/.agents/skills/ for personal use. Copy the folder there, then invoke it as $scansuite (see OpenAI's Codex skills guide):
cp -r scansuite-ci/plugins/scansuite/skills/scansuite ~/.agents/skills/scansuiteGitHub Copilot
Copilot reads skills from .github/skills/ in a repository (it also accepts .claude/skills/ and .agents/skills/) and from ~/.copilot/skills/ for personal use. Copy the folder there, then enable it with /skills in a Copilot CLI session (see GitHub's Copilot skills documentation):
cp -r scansuite-ci/plugins/scansuite/skills/scansuite .github/skills/scansuiteCodex and Copilot both read .agents/skills/, so one copy there serves both. Support and exact paths are the vendors' own; check their documentation for your version.
Check that it works
Ask the agent to run the skill's preflight (scripts/preflight.sh in the skill folder). It prints:
- the client and server versions;
- the token's role, permissions and expiry date;
- every scanner the server offers, with the ones it cannot run for your team marked
NOT AVAILABLEand the reason (for example a scanner whose integration is not set up, or AI scanners when the team has no AI provider).
A refused token prints the reason (expired, revoked, another team, unknown); the fixes are in CI/CD and automation.
Use it
Ask in plain language; the agent picks the scan and runs it. For example:
| You say | What runs |
|---|---|
| "Scan this repo for exploitable vulnerabilities and tell me what is reachable." | AI SAST of the working directory, findings by severity. |
| "Run OSINT on example.com, then a full-TCP port scan of the hosts it finds (no ping)." | OSINT, then network discovery of the addresses that resolve and that you own. |
| "Scan registry.example.com/app:1.4 for CVEs." | A container image scan. |
| "Check staging.example.com for web vulnerabilities behind our login." | A DAST scan with an authentication header. |
| "Show me the critical findings from the last scan of the payments product." | Reads the results through the team API. |
| "Mark finding 506 as a false positive: it is a test fixture." | Triage through the team API. Needs a token with Change findings. |
Before it runs anything, the skill:
- asks before intrusive or costly scanners: the Bruteforcer (
hosts_bruter), the Deep Scan (zap_full), the AI pentest (ai_pentest) and the AI bundles, above allfull-ai; - scans only targets you named and own: names an OSINT scan turns up are resolved, and lookalike domains and addresses that are not yours are left out;
- checks that the team's target policy allows each target (a refused target stops the client with exit code 3) and that the scanner is available on your server;
- reads low-severity results from the report archive when they are not stored as findings.
It gives you a short summary per scan, not raw output. The scan types, options and exit codes it uses are in CI/CD and automation; the team API calls it makes, with the permission each needs, are in the skill's API reference.
Last reviewed 2026-10-19