Sign in

GreyNoise Block User Guide

What is GreyNoise Block

GreyNoise Block lets you automatically create and deploy IP blocklists based on real-world internet scanning and exploitation data. It uses intelligence collected by the GreyNoise Global Observation Grid (GOG), a distributed sensor network that captures mass scanning and exploitation attempts across the internet. By leveraging this data, you can quickly identify and block unwanted or malicious activity before it reaches your infrastructure.

Details about IP addresses and what has been observed by GreyNoise can be seen at: https://viz.greynoise.io

GreyNoise Block uses this activity-based data to let you create blocklists defined by custom queries. Each blocklist created contains IPv4 IP addresses observed directly by GreyNoise matching the query that is defined.

Important Note

Due to the nature of internet scanning, attackers may use a variety of different infrastructures on the internet to perform malicious tasks. As a result, GreyNoise may identify IP addresses as malicious even when they belong to legitimate business services used by attackers, such as CDNs and purchasable infrastructure. When creating a Blocklist within GreyNoise Block, these lists of IP addresses could include IPs for these business services that are used in other ways by an organization.

To address this, use your firewall’s whitelisting capabilities to add any IPs that are included in GreyNoise Block that should be allowed within your organization.

Getting Started

The Query Builder allows you to create IP lists that are based on the observed activity of an IP address. This leverages GNQL (GreyNoise Query Language) queries using a drag-and-drop interface.

Defining a Blocklist

Each Blocklist is built via a GreyNoise GNQL query, which uses observed activity to identify IPs that should be included. Block allows for two different methods to create a Blocklist: 1) use a template, which includes a pre-defined query or 2) build a query from scratch using the Advanced Query Builder.

Using a blocklist Template

The blocklist templates are pre-defined lists that can be quickly used to deploy a blocklist based on GreyNoise recommendations. To use a template:

  1. Click "Query Builder" in the main navigation header.
  2. Scroll or search through the available templates to select the desired blocklist.
  3. Review the Query Stats to understand the size and details of the resulting IP blocklist.
  4. Click the "Block These IPs" button to create a blocklist from the template.
  5. Configure the Blocklist Settings
    • Name: Give your blocklist a descriptive name.
    • IP Limit: Set the maximum number of IPs to return to match your firewall limits.

Using the Advanced Query Build

For users familiar with GreyNoise and GNQL, the Advanced Query Builder allows you to finely tune your blocklist based on the criteria specified. To use the Advanced Query Builder:

  1. Click "Query Builder" in the main navigation header.
  2. Click the "Advanced" button in the middle of the screen, right above the Template Search bar.
  3. Add blocks from the Query Fields sidebar to the Query Canvas to build out the query. For example, drag the Classification block onto the canvas and select "malicious" from the drop down.
  4. Review the Query Stats to understand the size and details of the resulting IP blocklist.
  5. Click the "Block These IPs" button to create a blocklist from the advanced query.
  6. Configure the Blocklist Settings
    • Name: Give your blocklist a descriptive name.
    • IP Limit: Set the maximum number of IPs to return to match your firewall limits.

Advanced Queries - Additional Information on Group Conditions

Using a group condition is often necessary when using the same block more than once with different values in a query. For example, if you want to create a query that matches IPs with more than one defined classification, follow these steps:

  1. Drag a classification block onto the canvas and set the value to malicious.
  2. Set the operator to OR.
  3. Drag a second classification block onto the canvas and set the value to suspicious.
  4. Select both classification blocks on the canvas.
  5. Click the Group button.

This should result in a query in the preview that looks similar to the following:

last_seen:10d AND spoofable:false AND (classification:malicious OR classification:suspicious)

Advanced Queries - Additional Information on Not Conditions

Using a Not condition allows for the ability to use a broader query and then subtract a smaller subset of information from that broader query. The Not condition is a toggle available for each Block parameter that is added to the canvas. By adding a new block to the canvas and toggling the Not operator on, this will remove that matching criteria from the results.

Examples:

  • To build a list of malicious IP addresses but exclude those that are from the United States:
    • Add a Classification block to the canvas and select malicious from the menu.
    • Add a Source Country block to the canvas, set the value to United States and click the Not option to enable it.
    • The resulting blocklist query should look as follows:

last_seen:1d AND spoofable:false AND classification:malicious AND -source_country:"United States"

  • To build a list of malicious IP address but exclude a single IP you don't want to be included:
    • Add a Classification block to the canvas and select malicious from the menu.
    • Add a CIDR Block block to the canvas, set the value to 1.2.3.4/32 and click the Not option to enable it.
    • The resulting blocklist query should look as follows:

last_seen:1d AND spoofable:false AND classification:malicious AND -ip:1.2.3.4/32

Deploying a Blocklist

Blocklists can be deployed to most common firewalls that support IP-based blocklists.

Using Header-Based Authentication

To deploy your blocklist using a custom request headers, follow these steps:

  1. In the Block UI, copy the blocklist URL.
  2. In your firewall, create a blocklist entry using that URL.
  3. In the blocklist configuration, add a request header named key.
  4. Copy your Block API key from your Account page.
  5. Set the header value to your API key.

Using Inline Authentication

To deploy your blocklist using in-line auth, follow these steps:

  1. In the Block UI, copy the blocklist URL.
  2. Copy your Block API key from your Account page.
  3. Append your API key to the end of the URL like this: ?key=YOUR_API_KEY.
  4. In your firewall, create a blocklist entry using that URL.

Managing Your Blocklists

You can view the currently configured blocklist by clicking on the My Blocklists link in the main navigation. Each account can have up to 10 blocklists enabled at a time.

The following actions are available for each blocklist:

  • Copy the blocklist URL via the Copy Icon.
  • View the IP Count (number of IPs being returned by the query) and IP Limit (IP limited defined).
  • View the Blocklist Status
    • Enabled - Blocklist is available for use.
    • Disabled - Blocklist is not available for use.
    • Provisioning - Blocklist is being prepared and will be enabled shortly.
  • Perform an Action on the Blocklist
    • Edit the Blocklist Query in the Query Builder.
    • Download the current list of IPs being returned by the Blocklist.
    • Disable or Enable the Blocklist.
    • Delete the Blocklist.

Important Notes

⚠️ Blocklists are not available immediately after creation. They usually take 5–10 minutes to process your query and generate the initial blocklist. Refresh the page after a few minutes.

After the initial build, blocklists refresh every hour with the latest data.

You can have up to 10 enabled blocklists at a time. Disabling a blocklist frees up a slot toward this limit.

For additional assistance, contact block@greynoise.io.

Query Glossary

This section provides detailed information about the different parameter blocks that you can use to build your query. Use these parameters to customize your queries in the Query Builder.

Always Included Parameters

Lookback with Classification (last_seen): The date GreyNoise most recently observed scanning activity from an IP. Select a lookback period at the top of the canvas to determine how recent the observed activity for each IP should be (e.g. choosing a value of 1 indicates all IPs in the list need to have been observed in the last day).

  • There are four values available for this selection, these classifications are defined as follows:
    • Malicious - Includes all IPs that have had observed malicious behavior in the defined timeframe.
    • Suspicious - Includes all IPs that have had observed suspicious behavior in the defined timeframe.
    • Benign - Includes all IPs that have had observed benign behavior in the defined timeframe.
    • Last Seen - Includes all IPs that have had any observed behavior in the defined timeframe.

Scope (spoofable): This IP address has been opportunistically scanning the Internet but has failed to complete a full TCP connection. Any reported activity could be spoofed.

Optional Parameters

CIDR Block (ip): Enter an IPv4 CIDR block (ex. 87.121.84.0/24) to create a blocklist that contains IPs from that CIDR block observed by the GOG.

First Seen (first_seen): The date that an IP Address was first observed by the GreyNoise Global Observation Grid. Specify how many days back to include IPs first seen by GreyNoise (1–10 days). For example, choosing a value of 1 indicates all IPs in the list need to have been observed for the first time in the last day.

Classification (classification): Each IP Address is applied a classification based on observed activity. These can be defined as:

  • Benign: IPs linked to verified, trustworthy actors such as legitimate companies, universities, search engines, or security researchers. This classification overrides malicious tags and is regularly audited.
  • Suspicious: IPs showing systematic probing or reconnaissance activity that falls between benign and malicious, serving as context for investigations rather than an immediate threat.
  • Malicious: IPs exhibiting one or more directly observed harmful behaviors (malicious tags).
  • Unknown: All other IPs engaged in scanning activity that do not meet the criteria for benign, malicious, or suspicious.

Select one or more classification to focus your blocklist on specific behavior you care about.

Tag Name (tags): Tags identify specific observed behaviors associated with an IP address. View the full list of GreyNoise tags and their definitions here.

Actor Name (actor): The benign actor associated with the IP address, such as Shodan, Censys, GoogleBot, etc.

CVE ID (cve): Enter a CVE identifier to block the IPs seen by the GOG attempting to exploit it.

Source Country (source_country): The full name of the country the scanning IP is geographically located in.

Video Tutorial