Docs

Scanning at the Enterprise Level

Suggest Edits

The Repeater mode of the Bright CLI is the best solution for organizations that cannot open a port in the firewall for inbound traffic or expose targets externally. If the scan target is closed within a private company network, the Bright engine cannot access it directly from the cloud, and in this case the Repeater will serve as a request-proxy between the Bright cloud engine and the scan target inside your private network. You can either connect a central Repeater to the entire network to run all scans through it, or connect multiple Repeaters to use them separately, for each specific project.

1454

Below you can find the following examples of running scans in the Repeater mode:

Scanning using the repeater deployed on a cloud instance (VM)

To scan a target in your local network (behind a firewall) in the Repeater mode, you can deploy the Repeater locally on your machine or use your cloud provider instead (for example, AWS, Azure, and so on).

When deployed locally, the Repeater disconnects once you close the console, shut down the machine, or in case of a network failure. If the Repeater disconnects during a scanning process, the scan gets disrupted automatically. By running the Repeater on a cloud instance (VM), you decrease the risk of accidental disruption of a scan. This also allows you to use the Repeater as an “always-on” option.

To deploy the Repeater on a cloud instance, you first need to create the instance. The process of instance creation differs for all cloud providers. Please see the documentation of your cloud provider for the instructions. For example, if you are using AWS, the instructions can be found here.

Once the instance is launched, you need to install the Bright CLI on it, using the NPM or Docker option. The installation option depends on the instance OS. You can find the CLI installation guide here.

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

Prerequisites

  • You have launched a cloud instance (VM) and installed the Bright CLI on it.
  • You have registered (created) the Repeater and copied the generated REPEATER_ID. See Managing Repeaters for more information.
  • 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. Activate the Repeater on the cloud instance:
brightsec-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --cluster https://app.brightsec.com
  1. 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 Bright cloud, which starts scanning the target via the deployed Repeater. 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.
  1. View the scan results.
    You can follow the scan status in the Bright app or by using the Bright CLI polling command.

Scanning in the repeater mode, via a custom proxy

You can scan a target in your local network so that all requests from the Bright cloud are securely pulled via your custom proxy, in the Repeater mode. This also allows you to monitor all the traffic used for scan-related communication between the Bright engine, Repeater, and local target. You can configure the protocol to only proxy either the internal (from the Repeater to the local target) or external (from the Repeater to the Bright engine) traffic.

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

Prerequisites

  • You have installed the Bright CLI.
  • You have registered (created) the Repeater and copied the generated REPEATER_ID. See Managing Repeaters for more information about handling Repeaters.
  • 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. Activate the Repeater and connect it to your proxy:
bright-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --proxy $SOCKS_URL --cluster https://app.brightsec.com

Here is an example of the proxy format: --proxy socks5://1.1.1.1

  • If you want to only proxy the traffic to the targets, then use the following command:
bright-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --proxy-target $SOCKS_URL --cluster https://app.brightsec.com
  • If you want to only proxy the traffic to Bright, then use the following command:
bright-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --proxy-bright $SOCKS_URL --cluster https://app.brightsec.com

📘

Notes:

  • Bright supports SOCKS4, SOCKS5, SOCKS4a, and SOCKS5h. If you specify SOCKS://<URL>, SOCKS5h is applied by default.
  • 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>).
  1. 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

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

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

Scanning from a private cloud in the Repeater mode

If you are using the Bright app on a private cloud, you can run a scan using the CLI in a regular way, specifying your private cluster instead of the common Bright app subdomain (so it looks like <https://your-private-cluster.brightsec.com>).

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

Prerequisites

  • You have installed the Bright CLI.
  • You have registered (created) the Repeater and copied the generated REPEATER_ID. See Managing Repeaters for more information.
  • 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. Activate the Repeater:
bright-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --cluster https://your-private-cluster.brightsec.com
  1. 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://your-private-cluster.brightsec.com --smart

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

📘

Notes:

  • 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.
  • 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.
  1. View the scan results.
    You can follow the scan status in the Bright app or by using the Bright CLI polling command.

Updated about 2 months ago