Reference

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.

View as Markdown

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.

Connect your AI agent to ScanSuite

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 the agent will do

What you wantWhat you useWhat it needs
Ask about ScanSuitePoint any assistant at the documentation.Nothing.
Let an agent install and administer itA 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 scanA 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:

SourceWhat it holdsUse it when
https://scansuite.eu/documentation/llms.txtAn 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.txtEvery page in one file, in sidebar order.An assistant that cannot browse: upload or paste the whole file.
Any page URL with .md appendedThat 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:

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.

TaskPage to give the agent
Check a server before installingTechnical Requirements
Install on a Linux serverInstall ScanSuite Teams
Install on Google Cloud or AzureInstall on Google Cloud, Install on Microsoft Azure
Replace the certificateSSL/TLS Setup
Something does not workTroubleshooting
Back up and restoreBackup and restore
From a fresh server to a first reportQuick 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:

TaskAn agent canA person does
Install, update, checkCheck 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, tokensNothing: 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, integrationsNothing.All of it, on the Teams page.
ProductsCreate and rename through the team API, or let a pipeline create them (scansuite-ci --create-product).Deleting a product.
Scans: static, web, infrastructure, AI pentestStart, follow, cancel and read them with scansuite-ci or the team API.Allowing the targets; confirming authorisation to test them.
SchedulesA schedule in the CI system (a GitLab pipeline schedule, cron) that runs scansuite-ci.Schedules on the ScanSuite Schedules page.
TriageRead 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.
AssetsRead, 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
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.
Products
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.
Scans
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.
Backup
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.

ScanSuite Teams

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.

Prompt
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 needHow to check
A team on a ScanSuite Teams server, and the Team admin role to issue a tokenThe Teams page says Your role in this team: Team admin.
bash, curl and python3 on the machine the agent runs onbash --version; curl --version; python3 --version
Docker, or the Python clientdocker --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 teamTeams page, Scanning tab, Check whether targets are allowed.
For AI scans: an AI provider for the teamThe 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

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

  2. 02
    Issue 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 SST

The 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 readsDefaultWhat 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-tokenAnother file that holds the token.
SCANSUITE_CLIENTthe Docker image appsec4u/scansuite-ci:1A 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:

text
/plugin marketplace add cepxeo/scansuite-ci
/plugin install scansuite@scansuite-ci

Or copy the folder into a skills directory: ~/.claude/skills/ for every project, or .claude/skills/ inside one repository:

bash
git clone https://github.com/cepxeo/scansuite-ci
cp -r scansuite-ci/plugins/scansuite/skills/scansuite ~/.claude/skills/scansuite

Claude (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):

bash
cp -r scansuite-ci/plugins/scansuite/skills/scansuite ~/.agents/skills/scansuite

GitHub 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):

bash
cp -r scansuite-ci/plugins/scansuite/skills/scansuite .github/skills/scansuite

Codex 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 AVAILABLE and 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 sayWhat 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 all full-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