Sudo Commands

The Sudo Commands API provides operations to manage a set of sudo commands (Sudo Command bundles). You can create any number of bundles, but each bundle can only contain up to 64 commands. You control the order of Sudo Command bundles by the name of each bundle. See Sudo command bundle.

List all Sudo Command bundles

Lists all Sudo Command bundles for your Team

This endpoint requires one of the following roles: resource_admin, security_admin, delegated_security_admin.

SecuritybearerAuth
Request
path Parameters
team_name
required
string

The name of your Team

query Parameters
count
integer <int32>

The number of objects per page

descending
boolean

The object order

offset
string

The offset value for pagination. The rel="next" and rel="prev" Link headers define the offset for subsequent or previous pages.

prev
boolean

The direction of paging

Responses
200

OK

get/v1/teams/{team_name}/sudo_command_bundles
Request samples
Response samples
application/json
{
  • "list": [
    • {
      },
    • {
      }
    ]
}

Create a Sudo Command bundle

Creates a Sudo Command bundle

This endpoint requires the following role: resource_admin.

SecuritybearerAuth
Request
path Parameters
team_name
required
string

The name of your Team

Request Body schema: application/json
add_env
Array of strings or null <regex> <= 32 items

A list of environment variables to include when running sudo commands. See the sudo documentation.

description
string [ 1 .. 255 ] characters

A description of the Sudo Command bundle

name
required
string <regex> [ 1 .. 255 ] characters ^[\w\-_.]+$

The name of the Sudo Command bundle. This controls the ordering of all bundles within your Team. See Sudo Command Bundle.

no_exec
boolean or null

Whether to allow commands to execute child processes

no_passwd
boolean or null
Default: true

Whether to require a password when sudo is run. This should generally not be used as Users don't require a password.

run_as
string or null <regex> [ 1 .. 64 ] characters ^([%]{0,1})((([#])(\d+))|([\w\-_.]+)|((?i)[A-...

A non-root user account used to run the command

set_env
boolean or null

Whether to allow overriding environment variables to commands

Array of objects or null [ 0 .. 64 ]

A list of commands to allow

Array
args
string

The args are only allowed for 'executable' command type

args_type
string (args_type)

The args_type is only allowed for the 'executable' command type

Enum: "any" "custom" "none"
command_type
required
string (command_type)
Enum: "directory" "executable" "raw"
command
required
string
sub_env
Array of strings or null <regex> <= 32 items

A list of environment variables to ignore when running the commands. See the sudo documentation.

Responses
201

Created

post/v1/teams/{team_name}/sudo_command_bundles
Request samples
application/json
{
  • "name": "create_directories",
  • "description": "can be empty",
  • "structured_commands": [
    • {
      }
    ],
  • "no_passwd": true,
  • "no_exec": false,
  • "set_env": false,
  • "add_env": null,
  • "sub_env": null
}
Response samples
application/json
{
  • "id": "4c218c35-b8fd-45f5-9e43-1c392c9079b0",
  • "created_at": "2024-07-29T23:15:38.203054971Z",
  • "created_by": "name.username",
  • "updated_at": "2024-07-29T23:15:38.203054971Z",
  • "updated_by": "name.username",
  • "name": "create_directories",
  • "description": "can be empty",
  • "structured_commands": [
    • {
      }
    ],
  • "run_as": "",
  • "no_passwd": true,
  • "no_exec": false,
  • "set_env": false,
  • "add_env": null,
  • "sub_env": null
}

Retrieve a Sudo Command bundle

Retrieves a specified Sudo Command bundle

This endpoint requires one of the following roles: resource_admin, security_admin, delegated_security_admin.

SecuritybearerAuth
Request
path Parameters
team_name
required
string

The name of your Team

sudo_command_bundle_id
required
string

The UUID of a Sudo Command bundle

Responses
200

OK

get/v1/teams/{team_name}/sudo_command_bundles/{sudo_command_bundle_id}
Request samples
Response samples
application/json
{
  • "id": "3a064d89-2984-47aa-bbda-91d637f09b8c",
  • "created_at": "2024-07-29T17:52:05.898261Z",
  • "created_by": "some-user",
  • "updated_at": "2024-07-29T17:52:05.898261Z",
  • "updated_by": "some-user",
  • "name": "create_directories",
  • "description": null,
  • "structured_commands": [
    • {
      }
    ],
  • "run_as": "",
  • "no_passwd": true,
  • "no_exec": false,
  • "set_env": false,
  • "add_env": null,
  • "sub_env": null
}

Update a Sudo Command bundle

Updates a specified Sudo Command bundle. You cannot modify a Sudo Command bundle that is referenced by an OPA Security Policy.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth
Request
path Parameters
team_name
required
string

The name of your Team

sudo_command_bundle_id
required
string

The UUID of a Sudo Command bundle

Request Body schema: application/json
required
add_env
Array of strings or null <regex> <= 32 items

A list of environment variables to include when running sudo commands. See the sudo documentation.

description
string [ 1 .. 255 ] characters

A description of the Sudo Command bundle

name
required
string <regex> [ 1 .. 255 ] characters ^[\w\-_.]+$

The name of the Sudo Command bundle. This controls the ordering of all bundles within your Team. See Sudo Command Bundle.

no_exec
boolean or null

Whether to allow commands to execute child processes

no_passwd
boolean or null
Default: true

Whether to require a password when sudo is run. This should generally not be used as Users don't require a password.

run_as
string or null <regex> [ 1 .. 64 ] characters ^([%]{0,1})((([#])(\d+))|([\w\-_.]+)|((?i)[A-...

A non-root user account used to run the command

set_env
boolean or null

Whether to allow overriding environment variables to commands

Array of objects or null [ 0 .. 64 ]

A list of commands to allow

Array
args
string

The args are only allowed for 'executable' command type

args_type
string (args_type)

The args_type is only allowed for the 'executable' command type

Enum: "any" "custom" "none"
command_type
required
string (command_type)
Enum: "directory" "executable" "raw"
command
required
string
sub_env
Array of strings or null <regex> <= 32 items

A list of environment variables to ignore when running the commands. See the sudo documentation.

Responses
204

No Content

put/v1/teams/{team_name}/sudo_command_bundles/{sudo_command_bundle_id}
Request samples
application/json
{
  • "name": "create_directories",
  • "description": "can be empty",
  • "structured_commands": [
    • {
      }
    ],
  • "no_passwd": true,
  • "no_exec": false,
  • "set_env": false,
  • "add_env": null,
  • "sub_env": null
}

Delete a Sudo Command bundle

Deletes the specified Sudo Command bundle. You cannot delete a Sudo Command bundle that is referenced by an OPA Security Policy.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth
Request
path Parameters
team_name
required
string

The name of your Team

sudo_command_bundle_id
required
string

The UUID of a Sudo Command bundle

Responses
204

No Content

delete/v1/teams/{team_name}/sudo_command_bundles/{sudo_command_bundle_id}
Request samples