This article guides you through the Application Programming Interfaces (APIs) scan target setup.
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. We will use the Term Swagger file within this document for better readability. 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="user@user.com",
* 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, we will keep 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, please don't hesitate to contact us.
Configuring Authentication
To use the API scanner with a protected API, you can configure authentication via Header fields or GET parameters. Open the project preferences and scroll to API Authentication. Click on 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. Please 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.
