SecurityAgent / Client / create_pentest

create_pentest

SecurityAgent.Client.create_pentest(**kwargs)

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.

See also: AWS API Documentation

Request Syntax

response = client.create_pentest(
    title='string',
    agentSpaceId='string',
    assets={
        'endpoints': [
            {
                'uri': 'string'
            },
        ],
        'actors': [
            {
                'identifier': 'string',
                'uris': [
                    'string',
                ],
                'authentication': {
                    'providerType': 'SECRETS_MANAGER'|'AWS_LAMBDA'|'AWS_IAM_ROLE'|'AWS_INTERNAL',
                    'value': 'string'
                },
                'description': 'string'
            },
        ],
        'documents': [
            {
                's3Location': 'string',
                'artifactId': 'string'
            },
        ],
        'sourceCode': [
            {
                's3Location': 'string'
            },
        ],
        'integratedRepositories': [
            {
                'integrationId': 'string',
                'providerResourceId': 'string'
            },
        ]
    },
    excludeRiskTypes=[
        'CROSS_SITE_SCRIPTING'|'DEFAULT_CREDENTIALS'|'INSECURE_DIRECT_OBJECT_REFERENCE'|'PRIVILEGE_ESCALATION'|'SERVER_SIDE_TEMPLATE_INJECTION'|'COMMAND_INJECTION'|'CODE_INJECTION'|'SQL_INJECTION'|'ARBITRARY_FILE_UPLOAD'|'INSECURE_DESERIALIZATION'|'LOCAL_FILE_INCLUSION'|'INFORMATION_DISCLOSURE'|'PATH_TRAVERSAL'|'SERVER_SIDE_REQUEST_FORGERY'|'JSON_WEB_TOKEN_VULNERABILITIES'|'XML_EXTERNAL_ENTITY'|'FILE_DELETION'|'OTHER'|'GRAPHQL_VULNERABILITIES'|'BUSINESS_LOGIC_VULNERABILITIES'|'CRYPTOGRAPHIC_VULNERABILITIES'|'DENIAL_OF_SERVICE'|'FILE_ACCESS'|'FILE_CREATION'|'DATABASE_MODIFICATION'|'DATABASE_ACCESS'|'OUTBOUND_SERVICE_REQUEST'|'UNKNOWN',
    ],
    serviceRole='string',
    logConfig={
        'logGroup': 'string',
        'logStream': 'string'
    },
    vpcConfig={
        'vpcArn': 'string',
        'securityGroupArns': [
            'string',
        ],
        'subnetArns': [
            'string',
        ]
    },
    networkTrafficConfig={
        'rules': [
            {
                'effect': 'ALLOW'|'DENY',
                'pattern': 'string',
                'networkTrafficRuleType': 'URL'
            },
        ],
        'customHeaders': [
            {
                'name': 'string',
                'value': 'string'
            },
        ]
    },
    codeRemediationStrategy='AUTOMATIC'|'DISABLED'
)

Parameters:

• title (string) –

  [REQUIRED]

  The title of the pentest.

• agentSpaceId (string) –

  [REQUIRED]

  The unique identifier of the agent space to create the pentest in.

• assets (dict) –

  The assets to include in the pentest, such as endpoints, actors, documents, and source code.

  • endpoints (list) –

    The list of endpoints to test during the pentest.

    • (dict) –

      Represents a target endpoint for penetration testing.

      • uri (string) –

        The URI of the endpoint.

  • actors (list) –

    The list of actors used during penetration testing.

    • (dict) –

      Represents an actor used during penetration testing. An actor defines a user or entity that interacts with the target application, including authentication credentials and target URIs.

      • identifier (string) –

        The unique identifier for the actor.

      • uris (list) –

        The list of URIs that the actor targets during testing.

        • (string) –

      • authentication (dict) –

        The authentication configuration for the actor.

        • providerType (string) –

          The type of authentication provider. Valid values include SECRETS_MANAGER, AWS_LAMBDA, AWS_IAM_ROLE, and AWS_INTERNAL.

        • value (string) –

          The authentication value, such as a secret ARN, Lambda function ARN, or IAM role ARN, depending on the provider type.

      • description (string) –

        A description of the actor.

  • documents (list) –

    The list of documents that provide context for the pentest.

    • (dict) –

      Represents a document that provides context for security testing.

      • s3Location (string) –

        The Amazon S3 location of the document.

      • artifactId (string) –

        The unique identifier of the artifact associated with the document.

  • sourceCode (list) –

    The list of source code repositories to analyze during the pentest.

    • (dict) –

      Represents a source code repository used for security analysis during a pentest.

      • s3Location (string) –

        The Amazon S3 location of the source code repository archive.

  • integratedRepositories (list) –

    The list of integrated repositories associated with the pentest.

    • (dict) –

      Represents a code repository that is integrated with the service through a third-party provider.

      • integrationId (string) – [REQUIRED]

        The unique identifier of the integration that provides access to the repository.

      • providerResourceId (string) – [REQUIRED]

        The provider-specific resource identifier for the repository.

• excludeRiskTypes (list) –

  The list of risk types to exclude from the pentest.

  • (string) –

    Type of security risk.

• serviceRole (string) – The IAM service role to use for the pentest.

• logConfig (dict) –

  The CloudWatch Logs configuration for the pentest.

  • logGroup (string) –

    The name of the CloudWatch log group.

  • logStream (string) –

    The name of the CloudWatch log stream.

• vpcConfig (dict) –

  The VPC configuration for the pentest.

  • vpcArn (string) –

    The Amazon Resource Name (ARN) of the VPC.

  • securityGroupArns (list) –

    The Amazon Resource Names (ARNs) of the security groups for the VPC configuration.

    • (string) –

      ARN or ID of a security group.

  • subnetArns (list) –

    The Amazon Resource Names (ARNs) of the subnets for the VPC configuration.

    • (string) –

      ARN or ID of a subnet.

• networkTrafficConfig (dict) –

  The network traffic configuration for the pentest, including custom headers and traffic rules.

  • rules (list) –

    The list of network traffic rules that control which URLs are allowed or denied during testing.

    • (dict) –

      A rule that controls network traffic during penetration testing by allowing or denying traffic to specific URL patterns.

      • effect (string) –

        The effect of the rule. Valid values are ALLOW and DENY.

      • pattern (string) –

        The URL pattern to match for the rule.

      • networkTrafficRuleType (string) –

        The type of the network traffic rule. Currently, only URL is supported.

  • customHeaders (list) –

    The list of custom HTTP headers to include in network traffic during testing.

    • (dict) –

      A custom HTTP header to include in network traffic during penetration testing.

      • name (string) –

        The name of the custom header.

      • value (string) –

        The value of the custom header.

• codeRemediationStrategy (string) – The code remediation strategy for the pentest. Valid values are AUTOMATIC and DISABLED.

Return type:

dict

Returns:

Response Syntax

{
    'pentestId': 'string',
    'title': 'string',
    'createdAt': datetime(2015, 1, 1),
    'updatedAt': datetime(2015, 1, 1),
    'assets': {
        'endpoints': [
            {
                'uri': 'string'
            },
        ],
        'actors': [
            {
                'identifier': 'string',
                'uris': [
                    'string',
                ],
                'authentication': {
                    'providerType': 'SECRETS_MANAGER'|'AWS_LAMBDA'|'AWS_IAM_ROLE'|'AWS_INTERNAL',
                    'value': 'string'
                },
                'description': 'string'
            },
        ],
        'documents': [
            {
                's3Location': 'string',
                'artifactId': 'string'
            },
        ],
        'sourceCode': [
            {
                's3Location': 'string'
            },
        ],
        'integratedRepositories': [
            {
                'integrationId': 'string',
                'providerResourceId': 'string'
            },
        ]
    },
    'excludeRiskTypes': [
        'CROSS_SITE_SCRIPTING'|'DEFAULT_CREDENTIALS'|'INSECURE_DIRECT_OBJECT_REFERENCE'|'PRIVILEGE_ESCALATION'|'SERVER_SIDE_TEMPLATE_INJECTION'|'COMMAND_INJECTION'|'CODE_INJECTION'|'SQL_INJECTION'|'ARBITRARY_FILE_UPLOAD'|'INSECURE_DESERIALIZATION'|'LOCAL_FILE_INCLUSION'|'INFORMATION_DISCLOSURE'|'PATH_TRAVERSAL'|'SERVER_SIDE_REQUEST_FORGERY'|'JSON_WEB_TOKEN_VULNERABILITIES'|'XML_EXTERNAL_ENTITY'|'FILE_DELETION'|'OTHER'|'GRAPHQL_VULNERABILITIES'|'BUSINESS_LOGIC_VULNERABILITIES'|'CRYPTOGRAPHIC_VULNERABILITIES'|'DENIAL_OF_SERVICE'|'FILE_ACCESS'|'FILE_CREATION'|'DATABASE_MODIFICATION'|'DATABASE_ACCESS'|'OUTBOUND_SERVICE_REQUEST'|'UNKNOWN',
    ],
    'serviceRole': 'string',
    'logConfig': {
        'logGroup': 'string',
        'logStream': 'string'
    },
    'agentSpaceId': 'string'
}

Response Structure

• (dict) –

  Output for the CreatePentest operation.

  • pentestId (string) –

    The unique identifier of the created pentest.

  • title (string) –

    The title of the pentest.

  • createdAt (datetime) –

    The date and time the pentest was created, in UTC format.

  • updatedAt (datetime) –

    The date and time the pentest was last updated, in UTC format.

  • assets (dict) –

    The assets included in the pentest.

    • endpoints (list) –

      The list of endpoints to test during the pentest.

      • (dict) –

        Represents a target endpoint for penetration testing.

        • uri (string) –

          The URI of the endpoint.

    • actors (list) –

      The list of actors used during penetration testing.

      • (dict) –

        Represents an actor used during penetration testing. An actor defines a user or entity that interacts with the target application, including authentication credentials and target URIs.

        • identifier (string) –

          The unique identifier for the actor.

        • uris (list) –

          The list of URIs that the actor targets during testing.

          • (string) –

        • authentication (dict) –

          The authentication configuration for the actor.

          • providerType (string) –

            The type of authentication provider. Valid values include SECRETS_MANAGER, AWS_LAMBDA, AWS_IAM_ROLE, and AWS_INTERNAL.

          • value (string) –

            The authentication value, such as a secret ARN, Lambda function ARN, or IAM role ARN, depending on the provider type.

        • description (string) –

          A description of the actor.

    • documents (list) –

      The list of documents that provide context for the pentest.

      • (dict) –

        Represents a document that provides context for security testing.

        • s3Location (string) –

          The Amazon S3 location of the document.

        • artifactId (string) –

          The unique identifier of the artifact associated with the document.

    • sourceCode (list) –

      The list of source code repositories to analyze during the pentest.

      • (dict) –

        Represents a source code repository used for security analysis during a pentest.

        • s3Location (string) –

          The Amazon S3 location of the source code repository archive.

    • integratedRepositories (list) –

      The list of integrated repositories associated with the pentest.

      • (dict) –

        Represents a code repository that is integrated with the service through a third-party provider.

        • integrationId (string) –

          The unique identifier of the integration that provides access to the repository.

        • providerResourceId (string) –

          The provider-specific resource identifier for the repository.

  • excludeRiskTypes (list) –

    The list of risk types excluded from the pentest.

    • (string) –

      Type of security risk.

  • serviceRole (string) –

    The IAM service role used for the pentest.

  • logConfig (dict) –

    The CloudWatch Logs configuration for the pentest.

    • logGroup (string) –

      The name of the CloudWatch log group.

    • logStream (string) –

      The name of the CloudWatch log stream.

  • agentSpaceId (string) –

    The unique identifier of the agent space that contains the pentest.