How to Scan an API

To scan an application programming interface (API), the security scanner needs to get the security scan starting point. This starting point is a Swagger 2.0 or OpenAPI v3 file, a machine-readable API description. The security scanner will read the swagger file before each scan and scan the single endpoints for vulnerabilities.

Configuring a Project

When creating a project, you may configure the path of the Swagger file as shown in the following screenshot. The swagger file can be a JSON or YAML file.

When creating the Swagger file, ensure the defined host matches the project URL. For example, to confirm whether your Swagger file is valid, you can use https://editor.swagger.io/.

Using annotations, the best way to create your Swagger file is to generate it from your API source code. An example of a Swagger Annotation for PHP looks as follows:

* @OA\Post(  
*   path="/auth/login",  
*   summary="Login a user",  
*   operationId="postLogin",  
*   tags={"auth"},  
*   @OA\Parameter(  
*     name="email",  
*     description="Email address of the user",  
*     required=true,  
*     example="[email protected]",  
*     in="query",  
*     @OA\Schema(type="string")  
*   ),  
*   @OA\Parameter(  
*     name="password",  
*     description="Password of the user",  
*     required=true,  
*     example="12345678"  
*     in="query",  
*     @OA\Schema(type="string")  
*   ),  
*   @OA\Response(response=500, description="internal server error"),  
*   @OA\Response(  
*     response=200,  
*     description="The login response",  
*     @OA\Schema(  
*       type="object",  
*       @OA\Property(property="token", type="string", description="JWT Token for user authentication")  
*     )  
*   )  
* )

You can use example values inside your Swagger file to provide valid data for the security scanner. When doing an injection in any field, Crashtest Security keeps the other areas stable based on the value defined as the example value. Therefore, it is best to provide example values as described in the Swagger Documentation.

If you need help creating your Swagger file, contact Veracode Technical Support.

Configuring Authentication

To use the API scanner with a protected API, you can configure authentication with Header fields or GET parameters. Open the project preferences and scroll to API Authentication. Select the + icon to add a new authentication method.

Using an HTTP header such as a JWT Token will be sent with each request used for scanning the API as a header field. If you choose GET Parameter as the authentication type, the parameter will be added to each request as GET parameter. This is useful, e.g., if you are using an API key. Ensure that the token you provide has a long enough life to complete the full scan while logged in.

After configuring the parameters, you can check that they are set correctly.