This guide is designed to match the needs of the following users:

• Users who decided to try the Bright CLI for the first time and want to run a simple scan to see how it works.
• Developers who need to run security scans against a target on their own local machine. There is no need for deployment, they can scan whenever they need it, throughout the development process.

If you have not found your situation in the list above, please check out other use cases in the Getting Started section. You can also reach out to us at [email protected] or join our discord channel to ask your questions directly.

For more information about the Bright CLI purpose and features, see About Bright CLI.

Below you can find the following examples of running scans via the Bright CLI:

• Running a simple scan with a crawler (works for websites and web applications)
• Scanning specific interactions, pages, or features using a .HAR file (works for websites, web applications and APIs)
• Scanning API endpoints directly from a schema (for example, OpenAPI, Postman)
• Scanning applications behind your firewall, from the cloud, in the Repeater mode

📘

Note

Sample variables below are marked with a $. You must substitute them for your real values.

Runinging a simple scan with a crawler

Bright can crawl your web application to define the attack surface of the target and optimize the selected security tests. For that, you simply need to specify the URL of the target to start mapping from.

If you want to run a scan with a crawler using the Bright app, read here.

Prerequisites

• You have installed the Bright CLI.
• You have a valid AUTH_TOKEN (API key) with the following scopes: scans, files:write, org:read, and projects:read. You can create an organization API key or a personal API key.
• You have copied the Project ID under which you want to run a scan. A project ID is required. If you do not have any custom projects, use the Default project ID.

Step-by-step guide

1. Start a new scan with a crawler:

bright-cli scan:run --token $AUTH_TOKEN --name "Bright Scan" --project $PROJECT_ID --crawler "https://www.example.com" --cluster https://app.brightsec.com --smart

This command initializes a new scan engine in the cloud, which starts scanning the target. The crawler discovery type is used as an example.

👍

Tips

• If you are using the Bright app on a private cloud, ensure you specify the custom cluster instead of <https://app.brightsec.com>.
• To optimize the scan coverage and time, we are using the --smart option. This enables you to use automatic smart decisions, such as parameter skipping, detection phases and so on.

2. View the scan results.
   You can follow the scan status in the Bright app or by using the Bright CLI polling command.

Scanning specific interactions, pages, or features using a .HAR file

Bright uses data recorded in .HAR files to define the scope of the security scan and optimize the selected security tests. Using a .HAR, you can easily run a scan on a specific part of your application, instead of testing the entire target, perfect to test a new feature, specific Entrypoint or flow in your application. This will greatly reduce the scope of the testing, resulting in significantly shorter scan times.

If you want to run a scan with a .HAR file using the Bright app, read here.

Prerequisites

• You have installed the Bright CLI.
• You have uploaded the .HAR file to your Bright storage and copied the generated ID (FILE_ID). See Creating a HAR file to learn how to create a HAR file.
• You have a valid AUTH_TOKEN (API key) with the following scopes: scans, files:write, org:read, and projects:read. You can create an organization API key or a personal API key.
• You have copied the Project ID under which you want to run a scan. A project ID is required. If you do not have any custom projects, use the Default project ID.

Step-by-step guide

1. Start a new scan with the .HAR file uploaded to your Bright storage:

bright-cli scan:run --token $AUTH_TOKEN --name "Bright Scan" --project $PROJECT_ID --archive $FILE_ID --cluster https://app.brightsec.com --smart

📘

Note

Sample variables are marked with a $. You must substitute them for your real values.

This command initializes a new scan engine in the cloud, which starts scanning the target. The crawler discovery type is used as an example.

👍

Tips

• If you are using the Bright app on a private cloud, ensure you specify the custom cluster instead of <https://app.brightsec.com> (for example, <https://my-cluster.brightsec.com>).
• To optimize the scan coverage and time, we are using the --smart option. This enables you to use automatic smart decisions, such as parameter skipping, detection phases and so on.
• You can also set the crawler to scan only specific hosts using the --host-filter option. For example:

Bash

bright-cli scan:run --token $AUTH_TOKEN --name "Bright Scan" --project $PROJECT_ID --crawler "https://www.example.com" --host-filter "https://www.host-1.com" "https://www.host-2.com"--cluster https://app.brightsec.com --smart

2. Viewing the Scan Results.
   You can follow the scan status in the Bright app or by using the Bright CLI polling command.

Scanning API endpoints based on a schema

Bright can parse an uploaded API schema to define the attack surface of the target and optimize the selected security tests. The following versions of the API schemas are supported: Swagger 2+, OpenAPI 3+, Postman 2+. To ensure proper scanning of your API, you must configure the schema according to the general specification and specific Bright requirements. Find more information about the configuration validation here.

If you want to scan API endpoints using the Bright app, read here.

Prerequisites

• You have installed the Bright CLI.
• You have uploaded the API schema you want to scan to your Bright storage and copied the generated ID (FILE_ID).
• You have a valid AUTH_TOKEN (API key) with the following scopes: scans, files:write, org:read, and projects:read. You can create an organization API key or a personal API key.
• You have copied the Project ID under which you want to run a scan. A project ID is required. If you do not have any custom projects, use the Default project ID.

Step-by-step guide

1. Start a new scan with the API schema uploaded to your Bright storage:

bright-cli scan:run --token $AUTH_TOKEN --name "Bright Scan" --project $PROJECT_ID --archive $FILE_ID --cluster https://app.brightsec.com --smart

📘

Note

Sample variables are marked with a $. You must substitute them for your real values.

This command initializes a new scan engine in the cloud, which starts scanning the target. The crawler discovery type is used as an example.

👍

Tips

• If you are using the Bright app on a private cloud, ensure you specify the custom cluster instead of <https://app.brightsec.com> (for example, <https://my-cluster.brightsec.com>).
• To optimize the scan coverage and time, we are using the --smart option. This enables you to use automatic smart decisions, such as parameter skipping, detection phases and so on.

2. View the scan results.
   You can follow the scan status in the Bright app or by using the Bright CLI polling command.

Scanning applications behind your firewall, from the Bright cloud, in the Repeater mode

To scan targets in your private environment, for example, an application which is currently under development and cannot be exposed externally, you need to use a Repeater. If the scan target is closed within your network or protected by a firewall, the Bright engine cannot access it directly from the cloud. The Repeater serves as a request-proxy between the Bright engine and a scan target in your private environment.

To scan in the Repeater mode, you first need to register (create) the Repeater in the Bright app, and then connect (activate) it to for the scan using the generated Repeater ID.

🚧

Important

To function properly, the Repeater must have an outbound connection to amq.app.brightsec.com via the AMQ protocol (over TLS) using port 5672 (or a private cloud using the relevant port). Other technical requirements for Repeater connection can be found here.

Prerequisites

• You have installed the Bright CLI.
• You have a valid AUTH_TOKEN (API key) with the following scopes: scans, files:write, org:read, and projects:read. You can create an organization API key or a personal API key.
• You have copied the Project ID under which you want to run a scan. A project ID is required. If you do not have any custom projects, use the Default project ID.
• You have registered the Repeater in the Bright app and copied the generated REPEATER_ID. See Managing Repeaters for more information.

Step-by-step guide

1. Activate the Repeater:

bright-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --cluster https://app.brightsec.com

2. Start a new scan with a crawler:

bright-cli scan:run --token $AUTH_TOKEN --repeater $REPEATER_ID --name "Bright Scan" --project $PROJECT_ID --crawler "https://www.example.com" --cluster https://app.brightsec.com --smart

📘

Note

Sample variables are marked with a $. You must substitute them for your real values.

This command initializes a new scan engine in the cloud, which starts scanning the target in the Repeater mode. The crawler discovery type is used as an example.

The Repeater must stay active during the whole scanning session. Closing the console or shutting down your machine will disconnect the Repeater and lead to the scan disruption.

👍

Tips

• If you are using the Bright app on a private cloud, ensure you specify the custom cluster instead of <https://app.brightsec.com> (for example, <https://my-cluster.brightsec.com>).
• To optimize the scan coverage and time, we are using the --smart option. This enables you to use automatic smart decisions, such as parameter skipping, detection phases and so on.

3. View the scan results.
   You can follow the scan status in the Bright app or by using the Bright CLI polling command.