Configure Cloud IDS

Use these instructions to configure Cloud IDS for your application. For conceptual information about Cloud IDS, see the Cloud IDS overview.

Before you begin

Before you configure Cloud IDS, you must complete the following requirements.

Set up IAM permissions for Cloud IDS

Cloud IDS has several Identity and Access Management (IAM) roles. You can use the example commands to grant a principal the necessary IAM permissions.

Cloud IDS Admin role (roles/ids.admin). Project principals with this role can create IDS endpoints. If you are a project owner, you already have this permission and don't need an explicit ids.admin role to create IDS endpoints.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/ids.admin \
   --member=user:USER_NAME ;
```
This role enables the following operations:
- Create endpoint
- Delete endpoint
- Get endpoint
- List endpoint
Cloud IDS Viewer role (roles/ids.viewer). Project viewers and principals with this role have read-only access to IDS endpoints. If you are a project owner, editor, or viewer, you already have this permission.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/ids.viewer \
   --member=user:USER_NAME ;
```
Compute packet mirroring user role (roles/compute.packetMirroringUser). A role needed to attach a packet mirroring policy to the IDS endpoint. If you have the compute.securityAdmin or container.serviceAgent role, you already have this permission. For more information about this role, see the IAM basic and predefined roles reference.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/compute.packetMirroringUser \
   --member=user:USER_NAME ;
```
Logs Viewer role (roles/logging.viewer). An additional role needed to view recent threats, which is a critical core feature of Cloud IDS. For more information about this role, see the Access control guide.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/logging.viewer \
   --member=user:USER_NAME ;
```

In addition, you need the following miscellaneous permissions:

compute.regions.list
compute.zones.list

Set up private services access

To create IDS endpoints, you must enable the Service Networking API, and set up network peering for the Virtual Private Cloud (VPC) network. This only needs to be done once per customer project and can be done by using the Google Cloud console or the Google Cloud CLI. When you allocate an IP address range, it must be an RFC 1918-compliant private IP address range (10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16), or endpoint creation fails.

Use the following steps to set up private services access:

Enable the Service Networking API by using the following command. Replace PROJECT_ID with your project ID.
```
gcloud services enable servicenetworking.googleapis.com \
 --project=PROJECT_ID
```
If you have not already allocated an IP address range in your network, you must allocate an IP range for Google services in your VPC network. In the following command, you can omit the addresses field and Google Cloud selects an unused address range in your VPC network:
```
gcloud compute addresses create RESERVED_RANGE_NAME \
  --global \
  --purpose=VPC_PEERING \
  --addresses=192.168.0.0 \
  --prefix-length=16 \
  --description="DESCRIPTION" \
  --network=VPC_NETWORK
```
Replace the following:
- RESERVED_RANGE_NAME: a name for the allocated range, such as my-allocated-range
- DESCRIPTION: a description for the range, such as allocated for my-service
- VPC_NETWORK: the name of your VPC network, such as my-vpc-network
Create a private connection to a service producer. The private connection establishes a VPC Network Peering connection between your VPC network and the service producer's network.

If you already have an existing private connection, use the gcloud services vpc-peerings update command to update it:
```
gcloud services vpc-peerings update \
  --service=servicenetworking.googleapis.com \
  --ranges=RESERVED_RANGE_NAME \
  --network=VPC_NETWORK \
  --project=PROJECT_ID
```
If you do not already have a private connection, use the gcloud services vpc-peerings connect command. This command initiates a long-running operation that returns an operation name.
```
gcloud services vpc-peerings connect \
  --service=servicenetworking.googleapis.com \
  --ranges=RESERVED_RANGE_NAME \
  --network=VPC_NETWORK \
  --project=PROJECT_ID
```
Replace the following:
- RESERVED_RANGE_NAME: the name of one or more allocated ranges
- VPC_NETWORK: the name of your VPC network
- PROJECT_ID: the ID of the project that contains your VPC network
To check whether the operation was successful, use the gcloud services vpc-peerings operations describe command:
```
gcloud services vpc-peerings operations describe \
    --name=OPERATION_NAME
```
Replace OPERATION_NAME with the operation name that was returned from the previous step.

Repeat steps 2 and 3 for each VPC network that you want to monitor.

Optional: Enable VPC Service Controls

After private services access is enabled, you can optionally enable VPC Service Controls on Cloud IDS. If enabled, run the services vpc-peerings enable-vpc-service-controls command to enable VPC Service Controls for all your peering connections:

gcloud services vpc-peerings enable-vpc-service-controls \
    --service=servicenetworking.googleapis.com \
    --network=VPC_NETWORK \
    --project=PROJECT_ID

Replace the following:

VPC_NETWORK: the name of your VPC network
PROJECT_ID: the ID of the project that contains your VPC network

Create a Cloud IDS endpoint

We recommend that you create an IDS endpoint for every region in which you have deployed workloads. You can also create multiple IDS endpoints per region. Use the following steps to create an IDS endpoint and assign it an IDS service profile.

Console

In the Google Cloud console, go to IDS Endpoints.

Go to IDS Endpoints

Configure the endpoint:

Click Create endpoint.
Enter a name in the Endpoint name field.
Optional: Enter a description in the Description field.
Click the Network drop-down list, and select the network that you want Cloud IDS to inspect.
Choose the region and zone of your network or subnet from the Region and Zone drop-down lists.
Click Continue.

Select the Cloud IDS service profile:

Click Select IDS service profile.
Under Minimum threat severity level, select the correct alert level.
Click Create. The creation process can take 10-15 minutes.

After the IDS endpoint is created, attach a Packet Mirroring policy to the IDS endpoint:

Select the Endpoints tab.
Next to the IDS endpoint, click Attach.
In the Policy name field, enter a name for the Packet Mirroring policy.
Click Next.
Choose the subnet or instances to mirror. You can select multiple subnets and instances.
Click Next.
Determine whether you want to mirror all traffic or filter traffic:
1. If you want to mirror all traffic, ensure that Mirror All Traffic is selected.
2. If you want to filter traffic based on protocol, IP address range, or ingress or egress traffic, select Mirror filtered traffic:
  1. Select either Allow all protocols or Allow specific protocols.
  2. Select either Allow all IP ranges or Allow specific IP ranges.
Click Submit. The endpoint is created.

Now you can check to see if any threat logs have been generated. The following steps are optional:

Click the IDS Threats tab.
Click a threat name to view the Threat details page for that threat.
Return to the Threats tab.
Click the Menu to the right of your IDS endpoint and select View threat logs.

gcloud

Optional flags

The commands in this section might have some or all of the following optional flags:

--no-async

Wait for the operation in progress to complete, rather than returning immediately.

--filter=EXPRESSION

Apply a Boolean filter EXPRESSION to each resource item to be listed. If the expression evaluates True, then that item is listed. For more details and examples of filter expressions, run $ gcloud topic filters. This flag interacts with other flags that are applied in this order: --flatten, --sort-by, --filter, --limit.

--limit=LIMIT

Maximum number of resources to list. The default is unlimited. This flag interacts with other flags that are applied in this order: --flatten, --sort-by, --filter, --limit.

--page-size=PAGE_SIZE

A Cloud IDS groups resource list output into pages. This flag specifies the maximum number of resources per page. The default is determined by the service if it supports paging; otherwise, it is unlimited (no paging). Paging can be applied before or after --filter and --limit depending on the service.

--sort-by=[FIELD,…]

A comma-separated list of resource field key names to sort by. The default order is ascending. Prefix a field with ``~´´ for descending order on that field. This flag interacts with other flags that are applied in this order: --flatten, --sort-by, --filter, --limit.

--uri

Print a list of resource URIs instead of the default output.

--threat-exceptions

A comma-separated list of threat IDs to exempt from alerting on this endpoint. Limited to 99 exceptions per endpoint.

Instructions

To create a new IDS endpoint, perform the following steps:

Use the command gcloud ids endpoints create. Replace ENDPOINT_NAME, VPC_NETWORK, ZONE, and SEVERITY with information that matches your application.

gcloud ids endpoints create ENDPOINT_NAME \
  --network=VPC_NETWORK \
  --zone=ZONE \
  --severity=SEVERITY \
 [--no-async] \
 [GCLOUD_WIDE_FLAG...]

The severity flag is required, and takes one of the following values:
- INFORMATIONAL
- LOW
- MEDIUM
- HIGH
- CRITICAL
After the endpoint has been created, attach a Packet Mirroring policy to it. First, obtain the URL from the endpoint_forwarding_rule field by using the following command:
```
gcloud ids endpoints describe ENDPOINT_NAME
```

Create the Packet Mirroring policy by using the following command:

gcloud compute packet-mirrorings create POLICY_NAME \
--region=REGION --collector-ilb=ENDPOINT_FORWARDING_RULE \
--network=VPC_NETWORK --mirrored-subnets=SUBNET

Packet Mirroring has several optional flags, including those that you can use to filter traffic based on protocol, IP address range, or ingress or egress traffic. For more information about these optional flags, see the Packet Mirroring reference.

To delete an IDS endpoint, use the command gcloud ids endpoints delete. Replace ENDPOINT_NAME, PROJECT_ID, and ZONE with information that matches your application:

gcloud ids endpoints delete ENDPOINT_NAME \
   [--project=PROJECT_ID] \
   [--zone=ZONE] \
   [--no-async] \
   [GCLOUD_WIDE_FLAG...]

To describe an IDS endpoint, use the command gcloud ids endpoints describe. Replace ENDPOINT_NAME, PROJECT_ID, and ZONE with information that matches your application:

gcloud ids endpoints describe ENDPOINT_NAME \
   [--project=PROJECT_ID] \
   [--zone=ZONE] \
   [GCLOUD_WIDE_FLAG...]

To list IDS endpoints, use the command gcloud ids endpoints list:

gcloud ids endpoints list /
    [--filter=EXPRESSION] \
    [--limit=LIMIT] \
    [--page-size=PAGE_SIZE] \
    [--sort-by=[FIELD,...]] \
    [--uri] \
    [GCLOUD_WIDE_FLAG...]

API

Cloud IDS endpoint resources have the following fields:

Field	Type	Field description
createTime	string	[Output Only] Creation timestamp in RFC 3339 text format.
updateTime	string	[Output Only] Last update timestamp in RFC 3339 text format.
name	string	[Output Only] Name of the endpoint in the format `projects/{project_id}/locations/{locationId}/endpoints/{endpointId}`.
network	string	Name of the VPC network that is connected to the IDS endpoint. This can either contain the VPC network name itself (like `"src-net"`) or the full URL to the network (like `"projects/{project_id}/global/networks/src-net"`). This field is required when creating the endpoint.
severity	string	The minimum alert severity level that is reported by the endpoint. Possible values are as follows: INFORMATIONAL LOW MEDIUM HIGH CRITICAL This field is required when creating the endpoint.
description	string	An optional description of the endpoint.
endpoint_forwarding_rule	string	[Output Only] URL of the endpoint's network address to which traffic is to be sent by Packet Mirroring.
endpoint	string	[Output Only] Internal IP address of the endpoint's network entry point.

To create a Cloud IDS endpoint, use an HTTP POST request like the following, replacing variables as appropriate. The ENDPOINT_NAME must be between 1-63 characters; must only contain lowercase letters, digits, and hyphens; must start with a lowercase letter; and cannot end with a hyphen.

POST https://ids.googleapis.com/v1/projects/PROJECT_NAME/locations/ZONE/endpoints?endpointId=ENDPOINT_NAME
{
    "network": "NETWORK_NAME",
    "severity": "SEVERITY_LEVEL",
}

To delete a Cloud IDS endpoint, use an HTTP DELETE request like the following, replacing variables as appropriate:

DELETE https://ids.googleapis.com/v1/projects/PROJECT_NAME/locations/ZONE/endpoints?endpointId=ENDPOINT_NAME

To get a Cloud IDS endpoint, use an HTTP GET request like the following, replacing variables as appropriate:

GET https://ids.googleapis.com/v1/projects/PROJECT_NAME/locations/ZONE/endpoints?endpointId=ENDPOINT_NAME

To list all Cloud IDS endpoints in a zone, use an HTTP GET request like the following, replacing variables as appropriate:

GET https://ids.googleapis.com/v1/projects/PROJECT_NAME/locations/ZONE/endpoints

Alternatively, to list all Cloud IDS endpoints in all zones, you can replace the ZONE with a hyphen like the following:

GET https://ids.googleapis.com/v1/projects/PROJECT_NAME/locations/-/endpoints

Optional: Configure threat exceptions

You can disable noisy or otherwise unnecessary threat IDs by using the --threat-exceptions flag when you create or update your Cloud IDS endpoint. The following example updates an existing Cloud IDS endpoint ENDPOINT_NAME to exempt the threat IDs THREAT_ID1 and THREAT_ID2:

   gcloud ids endpoints update ENDPOINT_NAME 

      --threat-exceptions=THREAT_ID1,THREAT_ID2