Docs
These docs are for v1.1. Click to read the latest docs for v1.2.

Scanning at the Enterprise Level

Suggest Edits

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

  • An organization that needs to scan targets within their local network, but cannot open a port in the firewall for inbound traffic.
  • An organization that needs to scan multiple targets of different teams in their private environments, without exposing the targets externally.

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.

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

🚧

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.
  • Please contact the Bright Sales or Sales Engineering team for Proof of Concept (PoC) related environment details, configurations of repeaters, IP addresses, and ports for repeater connectivity.

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.

🚧

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.

Please contact Bright Sales/Sales Engineering team for Proof of Concept(PoC) related environment details/configurations of repeaters, IP addresses and ports for repeater connectivity, and so on.

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.

🚧

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.

Please contact Bright Sales/Sales Engineering team for Proof of Concept(PoC) related environment details/configurations of repeaters, IP addresses and ports for repeater connectivity, and so on.

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 internal traffic, then use the following command:
bright-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --proxy-internal $SOCKS_URL --cluster https://app.brightsec.com
  • If you want to only proxy the external traffic, then use the following command:
bright-cli repeater --token $AUTH_TOKEN --id $REPEATER_ID --proxy-external $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.
  • --proxy is mutually exclusive with --proxy-external and --proxy-internal.
  • 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.

📘

Notes

  • Sample variables are marked with a $. You must substitute them for your real values.
  • 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.

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.

🚧

Important

To function properly, the Repeater must have an outbound connection to the private cloud using the relevant port. Other technical requirements for Repeater connection can be found here.

Please contact Bright Sales/Sales Engineering team for Proof of Concept(PoC) related environment details/configurations of repeaters, IP addresses and ports for repeater connectivity, and so on.

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

  • Sample variables are marked with a $. You must substitute them for your real values.
  • 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 over 1 year ago