pentests

Creates, updates, deletes, gets or lists a pentests resource.

Overview

Name	pentests
Type	Resource
Id	aws.securityagent.pentests

Fields

The following fields are returned by SELECT queries:

batch_get_pentests

Name	Datatype	Description
not_found	array	The list of pentest identifiers that were not found.
pentests	array	The list of pentests that were found.

list_pentests

Name	Datatype	Description
agent_space_id	string	The unique identifier of the agent space that contains the pentest.
created_at	string (date-time)	The date and time the pentest was created, in UTC format.
pentest_id	string	The unique identifier of the pentest.
title_	string	The title of the pentest.
updated_at	string (date-time)	The date and time the pentest was last updated, in UTC format.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
batch_get_pentests	select	region		Retrieves information about one or more pentests in an agent space.
list_pentests	select	region		Returns a paginated list of pentest summaries for the specified agent space.
create_pentest	insert	region, title, agentSpaceId		Creates a new pentest configuration in an agent space. A pentest defines the security test parameters, including target assets, risk type exclusions, and logging configuration.
update_pentest	update	region, pentestId, agentSpaceId		Updates an existing pentest configuration.
batch_delete_pentests	exec	region, pentestIds, agentSpaceId		Deletes one or more pentests from an agent space.
start_pentest_job	exec	region, agentSpaceId, pentestId		Starts a new pentest job for a pentest configuration. The job executes the security tests defined in the pentest.
stop_pentest_job	exec	region, agentSpaceId, pentestJobId		Stops a running pentest job. The job transitions to a stopping state and then to stopped after cleanup completes.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

batch_get_pentests

Retrieves information about one or more pentests in an agent space.

SELECT
not_found,
pentests
FROM aws.securityagent.pentests
WHERE region = '{{ region }}' -- required
;

list_pentests

Returns a paginated list of pentest summaries for the specified agent space.

SELECT
agent_space_id,
created_at,
pentest_id,
title_,
updated_at
FROM aws.securityagent.pentests
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_pentest

Creates a new pentest configuration in an agent space. A pentest defines the security test parameters, including target assets, risk type exclusions, and logging configuration.

INSERT INTO aws.securityagent.pentests (
title,
agentSpaceId,
assets,
excludeRiskTypes,
serviceRole,
logConfig,
vpcConfig,
networkTrafficConfig,
codeRemediationStrategy,
disableManagedSkills,
maxTaskHours,
region
)
SELECT 
'{{ title }}' /* required */,
'{{ agentSpaceId }}' /* required */,
'{{ assets }}',
'{{ excludeRiskTypes }}',
'{{ serviceRole }}',
'{{ logConfig }}',
'{{ vpcConfig }}',
'{{ networkTrafficConfig }}',
'{{ codeRemediationStrategy }}',
'{{ disableManagedSkills }}',
{{ maxTaskHours }},
'{{ region }}'
RETURNING
agent_space_id,
assets,
created_at,
exclude_risk_types,
log_config,
pentest_id,
service_role,
title_,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: pentests
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the pentests resource.
  - name: title
    value: "{{ title }}"
  - name: agentSpaceId
    value: "{{ agentSpaceId }}"
  - name: assets
    description: |
      The collection of assets used in a pentest configuration, including endpoints, actors, documents, source code repositories, and integrated repositories.
    value:
      endpoints:
        - uri: "{{ uri }}"
      actors:
        - identifier: "{{ identifier }}"
          uris: "{{ uris }}"
          authentication:
            providerType: "{{ providerType }}"
            value: "{{ value }}"
          description: "{{ description }}"
          enableEmailMfa: {{ enableEmailMfa }}
          mfaForwardingAddress: "{{ mfaForwardingAddress }}"
      documents:
        - s3Location: "{{ s3Location }}"
          artifactId: "{{ artifactId }}"
          integratedDocument:
            integrationId: "{{ integrationId }}"
            resourceId: "{{ resourceId }}"
      sourceCode:
        - s3Location: "{{ s3Location }}"
      integratedRepositories:
        - integrationId: "{{ integrationId }}"
          providerResourceId: "{{ providerResourceId }}"
          branch: "{{ branch }}"
  - name: excludeRiskTypes
    value:
      - "{{ excludeRiskTypes }}"
  - name: serviceRole
    value: "{{ serviceRole }}"
    description: |
      ARN of an IAM role that the service can assume to access customer resources.
  - name: logConfig
    description: |
      The Amazon CloudWatch Logs configuration for pentest job logging.
    value:
      logGroup: "{{ logGroup }}"
      logStream: "{{ logStream }}"
  - name: vpcConfig
    description: |
      The VPC configuration for a pentest, specifying the VPC, security groups, and subnets to use during testing.
    value:
      vpcArn: "{{ vpcArn }}"
      securityGroupArns:
        - "{{ securityGroupArns }}"
      subnetArns:
        - "{{ subnetArns }}"
  - name: networkTrafficConfig
    description: |
      The network traffic configuration for a pentest, including custom headers and traffic rules.
    value:
      rules:
        - effect: "{{ effect }}"
          pattern_: "{{ pattern_ }}"
          networkTrafficRuleType: "{{ networkTrafficRuleType }}"
      customHeaders:
        - name: "{{ name }}"
          value: "{{ value }}"
  - name: codeRemediationStrategy
    value: "{{ codeRemediationStrategy }}"
    description: |
      Strategy for automated code remediation.
    valid_values: ['AUTOMATIC', 'DISABLED']
  - name: disableManagedSkills
    value:
      - "{{ disableManagedSkills }}"
    description: |
      A list of skill types.
  - name: maxTaskHours
    value: {{ maxTaskHours }}

UPDATE examples

update_pentest

Updates an existing pentest configuration.

UPDATE aws.securityagent.pentests
SET 
pentestId = '{{ pentestId }}',
agentSpaceId = '{{ agentSpaceId }}',
title = '{{ title }}',
assets = '{{ assets }}',
excludeRiskTypes = '{{ excludeRiskTypes }}',
serviceRole = '{{ serviceRole }}',
logConfig = '{{ logConfig }}',
vpcConfig = '{{ vpcConfig }}',
networkTrafficConfig = '{{ networkTrafficConfig }}',
codeRemediationStrategy = '{{ codeRemediationStrategy }}',
disableManagedSkills = '{{ disableManagedSkills }}',
maxTaskHours = {{ maxTaskHours }}
WHERE 
region = '{{ region }}' --required
AND pentestId = '{{ pentestId }}' --required
AND agentSpaceId = '{{ agentSpaceId }}' --required
RETURNING
agent_space_id,
assets,
created_at,
exclude_risk_types,
log_config,
pentest_id,
service_role,
title_,
updated_at;

Lifecycle Methods

batch_delete_pentests

Deletes one or more pentests from an agent space.

EXEC aws.securityagent.pentests.batch_delete_pentests 
@region='{{ region }}' --required 
@@json=
'{
"pentestIds": "{{ pentestIds }}", 
"agentSpaceId": "{{ agentSpaceId }}"
}'
;

start_pentest_job

Starts a new pentest job for a pentest configuration. The job executes the security tests defined in the pentest.

EXEC aws.securityagent.pentests.start_pentest_job 
@region='{{ region }}' --required 
@@json=
'{
"agentSpaceId": "{{ agentSpaceId }}", 
"pentestId": "{{ pentestId }}", 
"jobType": "{{ jobType }}", 
"selectedFindingIds": "{{ selectedFindingIds }}"
}'
;

stop_pentest_job

Stops a running pentest job. The job transitions to a stopping state and then to stopped after cleanup completes.

EXEC aws.securityagent.pentests.stop_pentest_job 
@region='{{ region }}' --required 
@@json=
'{
"agentSpaceId": "{{ agentSpaceId }}", 
"pentestJobId": "{{ pentestJobId }}"
}'
;