Scan using proxy server

Traceable's API security testing (AST) provides you an option to run security scans using a proxy server. This option is useful when you do not wish to instrument your application yet want to run AST scans. The Python proxy server is part of Traceable CLI. The proxy server talks to your application to send requests to your application and collects response. In that sense, the proxy server works as a data collector as well. Once the proxy server collects the request response data from your application, it sends the data to Traceable Platform agent, which sends it further to Traceable Platform. The following diagram shows a high-level function of the proxy server:

Running a scan through a Python proxy server requires that Traceable Platform agent to be already installed. Make a note of the IP address of your Platform agent, as this would be used when you run the scan. For more information on installing Traceable Platform agent, see the Platform agent topic. 

You can run the scans from the proxy server for the following three cases:

• On live traffic
• Using OpenAPI specification
• Using Postman collection

Set environment variables

Set the following environment variables before proceeding starting the scan using a proxy server.

export TRACEABLE_PROXY_HOST=localhost      // default is 0.0.0.0
export TRACEABLE_PROXY_PORT=18080          // default is 18080
export TA_SERVICE_NAME=service-name        // default is 'proxy'
unset http_proxy               // unset the http_proxy if its set to some other value

Live traffic

You can run AST scans on live traffic using the Python proxy server. You can either use a docker command or a Python command to run the scan. 

Python

Enter the following command:

traceable ast scan initAndRun --scan-name $NAME  --traffic-env $ENV  --token $API_TOKEN --traceable-server=api.traceable.ai:443 --proxy -tpa <IP_address_of_traceable_platform_agent:port>

Following is the explanation of the command:

• traceable: This is the command to invoke the Traceable CLI. 
• ast scan initAndRun: This is a command option specific to the image "traceableai/traceable-cli". It initiates a process called "initAndRun".
• --scan-name $NAME: Name of the scan.
• --traffic-env $ENV: Name of the environment on which the scan has to be run.
• --token $API_TOKEN: Traceable API token.
• --traceable-server=api.traceable.ai:443: This option sets the Traceable AI server address and port to api.traceable.ai:443.
• --proxy: This flag enables a proxy server configuration.
• -tpa <IP_address_of_traceable_platform_agent:port>: IP address of the Traceable Platform agent.

Docker

Enter the following command:

docker run -p 18080:18080 -it traceableai/traceable-cli ast scan initAndRun -e $ENV -n $NAME -tpa <IP_address_of_traceable_platform_agent:port> --token $TOKEN --traceable-server=api.traceable.ai:443 --proxy

Following is the explanation of the command:

• docker run: This is the Docker command used to run a container. 
• -p 18080:18080: This option maps the host port 18080 to the container port 18080. It allows incoming network connections to reach the container's application running on port 18080. 
• -it: This option enables an interactive session with the container.
• traceableai/traceable-cli: This is the name of the Docker image used to create the container.
• ast scan initAndRun: This is a command option specific to the image "traceableai/traceable-cli". It initiates a process called "initAndRun".
• -e $ENV: Name of the environment for which scan has to run.
• -n $NAME: Name of the scan.
• -tpa <IP_address_of_traceable_platform_agent>: IP address of Traceable Platform agent.
• --token $TOKEN: This is an environment variable for API token value passed to the container, where $TOKEN should be substituted with the actual value.
• --traceable-server=api.traceable.ai:443: This option sets the traceable server address and port.
• --proxy: This flag enables a proxy server configuration.
• -tpa <IP_address_of_traceable_platform_agent:port>: IP address of the Traceable Platform agent.

OpenAPI specification

You can run the AST scan using a proxy server for OpenAPI specifications using the following commands. 

Python

Enter the following command:

traceable ast scan initAndRun --scan-name $NAME  --policy $POLICY_WITH_OPEN_API_SPECS  --token $API_TOKEN --traceable-server=api.traceable.ai:443 --proxy -tpa <IP_address_of_traceable_platform_agent:port>

Following is an explanation of the command:

• traceable: This is the command to invoke the Traceable CLI. 
• ast scan initAndRun: This is a command option specific to the image "traceableai/traceable-cli". It initiates a process called "initAndRun".
• --scan-name $NAME: Name of the scan.
• --policy $POLICY_WITH_OPEN_API_SPECS: Name of the policy with OpenAPI specification.
• --token $API_TOKEN: Traceable API token.
• --traceable-server=api.traceable.ai:443: This option sets the Traceable AI server address and port to api.traceable.ai:443.
• --proxy: This flag enables the proxy server configuration.
• -tpa <IP_address_of_traceable_platform_agent:port>: IP address of the Traceable Platform agent.

Docker

Enter the following command:

docker run -p 18080:18080 -it traceableai/traceable-cli ast scan initAndRun -n $NAME --policy $POLICY_WITH_OPEN_API_SPECS -tpa <IP_address_of_traceable_platform_agent:port> --token $TOKEN --traceable-server=api-dev.traceable.ai:443 --proxy

Following is the explanation of the command:

• docker run: This is the Docker command used to run a container. 
• -p 18080:18080: This option maps the host port 18080 to the container port 18080. It allows incoming network connections to reach the container's application running on port 18080. 
• -it: This option enables an interactive session with the container.
• traceableai/traceable-cli: This is the name of the Docker image used to create the container.
• ast scan initAndRun: This is a command option specific to the image "traceableai/traceable-cli". It initiates a process called "initAndRun".
• -n $NAME: Name of the scan.
• --policy $POLICY_WITH_OPEN_API_SPECS: Name of the policy which has OpenAPI specification. Make sure that you already have such a policy created through the Platform UI. For more information, see Dashboard and policies.
• -tpa <IP_address_of_traceable_platform_agent:port>: IP address of Traceable Platform agent.
• --token $TOKEN: This is an environment variable for the API token.
• --traceable-server=api.traceable.ai:443: This option sets the traceable server address and port.
• --proxy: This flag enables a proxy server configuration.

Postman collection

Download the crAPI Postman collection from Github. Make a note of the location where you have downloaded the Postman collection. The path to the Postman collection is used in the following command. Make sure to edit the crAPI.postman_environment.json file and configure the values with keys, for example, url and url_mail point to the target URL. For example:

    "name": "Crapi",
    "values": [{
            "key": "url",
            "value": "http://1.2.3.4:80",   // target url
            "enabled": true
        },
        {
            "key": "url_mail",
            "value": "http://2.3.4.5:8025",   // target url
            "enabled": true
        },
        {
            "key": "video_file",
            "value": "./car.mp4",
            "enabled": true
        }
    ],

Python

Enter the following command:

traceable ast scan initAndRun --scan-name $NAME  --traffic-env $ENV  --token $TOKEN --traceable-server=api-dev.traceable.ai:443 --proxy -pc $PATH_TO_CRAPI_POSTMAN_COLLECTION -pe $PATH_TO_CRAPI_POSTMAN_ENVIRONMENT

Following is the explanation for the command:

• traceable: This is the command to invoke the Traceable AI CLI tool.
• ast scan initAndRun: This is a command option specific to the image "traceableai/traceable-cli". It initiates a process called "initAndRun".
• --scan-name $NAME: Name of the scan.
• --traffic-env $ENV: Name of the environment on which the scan has to be run.
• --token $TOKEN: Traceable API token.
• --traceable-server=api.traceable.ai:443: This option sets the traceable server address and port.
• --proxy: This flag enables a proxy server configuration.
• -pc $PATH_TO_CRAPI_POSTMAN_COLLECTION: This option sets the path to a Postman collection file.
• -pe $PATH_TO_CRAPI_POSTMAN_ENVIRONMENT: This option sets the path to a Postman environment file.

Docker

Enter the following command. Make sure to mount the volume containing the postman collection files using '-v' option.

docker run -v <HOST_MACHINE_PATH>:<CONTAINER_PATH> -p 18080:18080 -it traceableai/traceable-cli ast scan initAndRun -e $ENV -n $NAME -tpa <IP_address_of_traceable_platform_agent:port> --token $TOKEN --traceable-server=api.traceable.ai:443 --proxy -pc $PATH_TO_CRAPI_POSTMAN_COLLECTION -pe $PATH_TO_CRAPI_POSTMAN_ENVIRONMENT

Following is the explanation for the command:

• docker run: This is the Docker command used to run a container. 
• -p 18080:18080: This option maps the host port 18080 to the container port 18080. It allows incoming network connections to reach the container's application running on port 18080. 
• -it: This option enables an interactive session with the container.
• traceableai/traceable-cli: This is the name of the Docker image used to create the container.
• ast scan initAndRun: This is a command option specific to the image "traceableai/traceable-cli". It initiates a process called "initAndRun".
• -n $NAME: Name of the scan.
• -v <HOST_MACHINE_PATH>:<CONTAINER_PATH>: This option mounts a volume from the host machine to the container, allowing files and directories to be shared between them. <HOST_MACHINE_PATH> represents the path on the host machine, and <CONTAINER_PATH> represents the path inside the container. 
• -pc $PATH_TO_CRAPI_POSTMAN_COLLECTION: Path to the crAPI Postman collection.
• -pe $PATH_TO_CRAPI_POSTMAN_ENVIRONMENT: Path to crAPI Postman environment file.
• -tpa <IP_address_of_traceable_platform_agent:port>: IP address of Traceable Platform agent.
• --token $TOKEN: This is an environment variable for the API token.
• --traceable-server=api.traceable.ai:443: This option sets the traceable server address and port.
• --proxy: This flag enables a proxy server configuration.