Deployment: Invicti Platform on-demand, Invicti Platform on-premises
Permissions for internal agent scanning
Give your team exactly the access they need to install internal agents and scan internal sites, without handing out full access. This document explains which role permissions are required for each internal agent and scanning task, and how to avoid the most common access errors.
Why this matters
Installing an agent or starting a scan with the wrong role fails with a "Forbidden" error, often halfway through the setup. Granting the broadest role to avoid that problem gives users more access than they need. Knowing the exact permissions for each task lets you create a focused role once and assign it to everyone who works with internal agents.
Required permissions
The table lists the permissions a user needs for each task. A task that lists more than one permission requires all of them.
| Task | Required permissions |
|---|---|
| View the list of agents | Agents: Read |
| Install or update an agent | Agents: Read and Agents: Update |
| Generate a new agent token | Agents: Create |
| Assign an agent to a target, or remove it | Assets: Update (to remove, also Agents: Read and Agents: Update) |
| Delete an agent | Agents: Delete and Assets: Update |
| Upload a login sequence recording (LSR) file in the target settings | Assets: Update |
| Upload an API definition in the target settings | Assets: Update |
| Start or schedule a scan | Scans: Create |
| Stop, pause, or resume a scan | Scans: Update |
You don't need API Security permissions to upload an API definition to an existing target. API Security: Create or Assets: Create is only needed to create a new API target from a definition.
You don't need to grant Scans: Full for internal agent scanning. Scans: Create and Scans: Update cover starting and stopping scans.
- When you tick Create, Update, or Delete for a permission, the role editor also ticks Read for you.
- If you tick all four Agents operations (Read, Create, Update, and Delete), the role editor shows them as Full. This grants the same access as the four operations.
- If a role only installs and manages agents and doesn't delete them, tick Read, Update, and Create, and leave Delete unticked.
Permissions and collections
When you assign the role to a user, you can apply it to all collections or limit it to selected collections. For internal agent scanning, this affects the tasks differently:
- Agents permissions apply to the whole account. A user with a role limited to selected collections can still view, install, and manage agents.
- Assets permissions apply per target. Assigning an agent to a target and uploading an LSR file work only for targets in the collections assigned to the role.
For users who manage internal agents and assign them to targets across your account, don't click Select collections when you assign the role. By default, an assigned role applies to all current and future collections.
Set up a role for internal agent scanning
- Create a custom role with the permissions from the required permissions table that your team needs. For instructions, refer to the Create and manage roles document.
- Assign the role to each user who installs agents or runs internal scans. For instructions, refer to the Set or edit roles and collections for users document.
For the full list of permissions and what each one allows, refer to the Role permissions document.
Troubleshooting
I get a "Forbidden" error when installing an agent
Check that the user's role includes both Agents: Read and Agents: Update. If the user generates a new agent token, the role also needs Agents: Create.
I can't delete an agent
Deleting an agent requires both Agents: Delete and Assets: Update. Add the missing permission to the user's role and try again.
I can't upload an LSR file or an API definition
Uploading an LSR file or an API definition in the target settings requires Assets: Update. Check that the user's role includes this permission and that the target belongs to a collection assigned to the role.
The role has the right permissions, but the user still gets a "Forbidden" error on a specific target
Check whether the role is limited to selected collections and whether the target belongs to one of them. Assigning an agent to a target and uploading an LSR file work only for targets in the role's collections. Edit the user and add the target's collection, or remove the collection restriction so the role applies to all collections.
Need help?
Invicti Support team is ready to provide you with technical help. Go to Help Center