This page describes how to list, describe, dismiss, restore, and export insights.
Required roles and permissions
To get the permissions that you need to manage and export insights, ask your administrator to grant you the following IAM roles on your project:
-
Firewall Recommender Admin (
roles/recommender.firewallAdmin
) -
Firewall Recommender Viewer (
roles/recommender.firewallViewer
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
These predefined roles contain the permissions required to manage and export insights. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to manage and export insights:
-
recommender.computeFirewallInsights.list
-
recommender.computeFirewallInsights.update
You might also be able to get these permissions with custom roles or other predefined roles.
List insights for a project
To list the insights for a project, do the following:
gcloud
Use the gcloud recommender insights list
command:
gcloud recommender insights list \ --project=PROJECT_ID \ --location=global \ --insight-type=google.compute.firewall.Insight \ --filter=EXPRESSION \ --limit=LIMIT \ --page-size=PAGE_SIZE \ --sort-by=SORT_BY \ --format=json
Replace PROJECT_ID
with the project ID that you want to
list insights for.
The location
flag always uses the location named global
. The
insight-type
flag always uses the insight type named
google.compute.firewall.Insight
. Unless you
format the output in JSON, the command output is tabular.
The following fields are optional:
EXPRESSION
: apply this Boolean filter to each resource that you want to listIf the expression evaluates as
True
, that item is listed. For more details and examples of filter expressions, run$ gcloud topic filters
or see thegcloud topic filters
documentation.LIMIT
: the maximum number of resources to list; the default number of resources listed is unlimitedPAGE_SIZE
: the maximum number of resources to list per pageThe default page size is determined by the service; otherwise, there's no paging. Paging might be applied before or after
FILTER
andLIMIT
.SORT_BY
: a list of comma-separated field key names to sort by for a resourceThe default order is ascending. To specify a descending order, prefix a field with
~
(a tilde).
API
Make a GET
request to the
projects.locations.insightTypes.insights
method:
GET https://recommender.googleapis.com/v1/{parent=projects/*/locations/global/insightTypes/*}/insights
The following example shows a sample response for this command:
insights { "name": "projects/{project_number}/locations/global/insightTypes/google.compute.firewall.Insight/insights/{insight-id}" "description": "Firewall projects/{project_id}/global/firewalls/{shadowed_firewall_name} is shadowed by projects/{project_id}/global/firewalls/{shadowing_firewall_name}." "content": { "shadowingFirewalls": [ "//compute.googleapis.com/projects/{project_id}/global/firewalls/{shadowing_firewall_name1}" ] }, "lastRefreshTime": "2020-04-01T19:16:43Z", "observationPeriod": "0s", "stateInfo" { "state": "ACTIVE" } "category": "SECURITY" "targetResources":[ "//compute.googleapis.com/projects/{project_id}/global/firewalls/{shadowed_firewall_name}" ], "insightSubtype": "SHADOWED_RULE" }
Describe insights
To describe details about a particular firewall rule in a project, do the following:
gcloud
Use the gcloud recommender insights describe
command:
gcloud recommender insights describe INSIGHT_ID \ --project=PROJECT_NAME \ --location=global \ --insight-type=google.compute.firewall.Insight
Replace the following:
INSIGHT_ID
: the ID of the insight to describePROJECT_NAME
: the name of the project that you want to list insights for
The location
flag always uses the location named global
. The
insight-type
flag always uses the insight type named
google.compute.firewall.Insight
.
API
Make a GET
request to the
projects.locations.insightTypes.insights
method:
GET https://recommender.googleapis.com/v1/{name=projects/*/locations/global/insightTypes/*/insights/*} { "name": projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID, }
Replace the following:
PROJECT_ID
: the project IDLOCATION
: always use the location namedglobal
INSIGHT_TYPE_ID
: always use the valuegoogle.compute.firewall.Insight
INSIGHT_ID
: the ID for the insight
Mark an insight as dismissed
If any insight isn't meaningful, or if you want to hide it for any other reason, you can dismiss it. After you dismiss an insight, the Google Cloud console no longer displays the insight to you or other users unless you restore it.
To mark an insight as dismissed, do the following:
Console
In the Google Cloud console, go to the Firewall Insights page.
Find the appropriate card and click View full list.
Select the rules that you want to dismiss, and then click Dismiss.
Restore a dismissed insight
If you dismissed an insight that you later think is relevant, you or another user can restore it and make it visible in the Google Cloud console.
To restore a dismissed insight, do the following:
Console
In the Google Cloud console, go to the Firewall Insights page.
Click Dismiss History. In response, the Google Cloud console displays the Dismissed insights page.
Select the insights that you want to restore, and then click Restore.
Export insights
If needed, you can export shadowed and overly permissive rule insights in CSV
or JSON format. Deny rules with hits
information cannot be exported because
it is based on firewall stackdriver metrics and not on insights.
You might want to export insights for any of the following reasons:
- You need to import the data into another system.
- You want to access the data while you are offline.
- You intend to disable Firewall Insights, but you want to retain access to previously generated insights.
To export insights, do the following:
Console
In the Google Cloud console, go to the Firewall Insights page.
Click Save as.
Follow the prompts to choose a format for your insights and download them.
You can also export insights to BigQuery. When you export insights to BigQuery, you can view daily snapshots of insights for your organization. For more information, see Export recommendations to BigQuery.