API User Guide

Note

See the API Reference for Swagger documentation.

The Fugue API enables you to interact with Fugue to programmatically access data relating to your organization’s AWS and Azure environments, scans, and events.

A Fugue environment represents not just your infrastructure but the state of its compliance and whether it has changed (drifted) from its ideal configuration. Through this concept of an environment, Fugue is able to provide you with a comprehensive snapshot of your compliance state at any given moment. Once you set a baseline – a known-good configuration – Fugue monitors your resources for drift. The API provides an even more powerful way to manage, monitor, and enforce your infrastructure.

For example, you can use API clients to integrate Fugue into CI/CD pipelines or automate environment management tasks. More use cases are listed here.

_images/APIClientsTab.png

What is the Fugue API?

The Fugue API is a RESTful API. Through the API Clients page (accessible from the Organization link at the top right of the UI), users can create a client and retrieve its unique Client ID and Client Secret. After authenticating, they can start sending API requests with their preferred tool to retrieve compliance results, kick off an on-demand scan or adjust a scan schedule, generate a new IAM policy for Fugue, and more.

The API Clients page also allows you to delete a client and regenerate or revoke a Client Secret. For more information, see How to Use the API.

API Functions

The Fugue API supports the following operations:

You can find examples for each operation in Examples. For further information, see the Swagger documentation in API Reference.

Use Cases

The Fugue API supports many different use cases. Here are just a few examples:

On-Demand Environment Scanning

A user can create an environment on demand, scan it, assess compliance results by rule and resource type, and delete the environment.

Pre-Existing Environment Scanning

A user can establish a single environment and repeatedly scan it as their infrastructure evolves so they can understand their compliance status.

Events Integration

A user can retrieve event information from Fugue to drive internal communications or processes, such as Slack integrations or pager notifications.

Custom Reporting

A user can incorporate Fugue compliance results into their own internal reporting mechanisms or systems.

If you have a particular use case in mind, reach out to support@fugue.co so we can help you develop it.

How to Use the API

Ready to begin? Below are general instructions for using the Fugue API and navigating the API Clients page.

Getting Started

  1. In the API Clients page (accessible from the Organization link at the top right of the UI), create a new API Client and give it a name.

_images/APICreateNewClient.png

2. Copy the Client ID and Client Secret and store it securely.

_images/APIClientSecret.png

3. Use your preferred API tool to pass the Client ID and Secret in the Authorization HTTP header using Basic Auth.

_images/APIPostmanAuth.png

4. Send an API request to the appropriate endpoint including any required parameters.

_images/APIExampleRequest.png

API tools, authentication, and API requests are discussed in more detail later in this guide.

Understanding the API Clients Page

The API Clients page displays the Client Name, Client ID, Created Date, Status, Secret Age, and Last Activity for all clients in the organization.

_images/APIClientsTabAnnotated.png
  • Client Name: Name of the API client

  • Client ID: Unique ID of the client

  • Created Date: When the client was created

  • Status: Status of the client: Active, Created, or Secret Revoked.

    • Active indicates a client has been created, its Client ID and Client Secret have been generated, and the client is ready for use with the API.

    • Created indicates a client has been created but a Client ID and Client Secret were not generated.

    • Secret Revoked indicates a client has had its Client Secret revoked, preventing the client from communicating with the API.

  • Secret Age: Length of time secret has been active

  • Last Activity: When the client was last used

Revoking or Regenerating a Secret

When you revoke a secret, any scripts or applications that use that secret will stop working. It may take up to 5 minutes to revoke the secret.

When you generate a new secret, Fugue will also revoke the previous secret. Any scripts or applications that use the previous secret will stop working until you update them with the newly generated secret. It may take up to 5 minutes to revoke the previous secret.

  1. In the API Clients page, select the ellipsis ... next to the client you want to revoke and/or regenerate a secret for.

_images/APIEllipsisMenu.png

2. To revoke a secret, select Revoke Secret.

3. To regenerate a secret, select Generate New Secret.

Deleting an API Client

When you delete an API client, any scripts or applications that use an existing secret for that client will stop working. It may take up to 5 minutes to revoke the existing secret.

  1. In the API Clients page, select the ellipsis ... next to the client you want to delete.

  2. Select Delete Client.

_images/APIEllipsisDeleteClient.png

OpenAPI 2.0 Spec

The API is defined in an OpenAPI 2.0 specification (formerly known as Swagger 2.0).

The specification file is located at https://api.riskmanager.fugue.co/v0/swagger. The human-readable documentation with examples is in the API Reference. Finally, for an interactive version of the Swagger spec, see the Swagger UI.

Swagger UI

Swagger UI offers an interactive way to view the Fugue API specification.

_images/APISwaggerUI.png

Swagger UI allows you to test out the Fugue API with simulated results when using it anonymously and live results when you authenticate with the API. You can log in by selecting the Authorize button and entering your Client ID and Client Secret.

_images/APISwaggerAuth.png

Each API path features a Try it out button that allows you to interact with Fugue. You can adjust parameters and receive a simulated response if you haven’t provided authentication or a real response from the actual API if you have.

_images/APISwaggerTestButton.png

Either way, you’ll also get an automatically generated path and a curl command to send the API request. This request retrieves a list of details for all environments from the /environments endpoint:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/environments" \
  -u $CLIENT_ID:$CLIENT_SECRET

Curl and API requests are discussed in more detail later in this guide.

For non-interactive but more detailed Swagger documentation, including examples, see the API Reference.

Generating Clients

Swagger Editor and Swagger Codegen are two tools that can generate a client for a specific programming language.

Swagger Editor is a web application for generating an SDK. First, you’ll need to import the Swagger specification file. In the editor’s File menu, select Import URL and paste the URL of the Swagger spec:

https://api.riskmanager.fugue.co/v0/swagger
_images/APISwaggerEditorImport.png

Alternatively, you can copy and paste the YAML from the Swagger spec.

In the Generate Client menu, select the language you want to download an SDK for.

_images/SwaggerEditorGenerate.png

Swagger Codegen is a command-line tool that generates an SDK for a given language. You’ll find its documentation on Github.

If you’ve installed Swagger Codegen through Homebrew, generate a client with the following command, substituting ruby for the language of your choice:

swagger-codegen generate -i https://api.riskmanager.fugue.co/v0/swagger -l ruby -o /tmp/test/

If you’ve installed Swagger Codegen from another source and are not using Windows, use the following command:

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
   -i https://api.riskmanager.fugue.co/v0/swagger \
   -l ruby \
   -o /var/tmp/ruby_api_client

If you’re using Windows, use the following command:

java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i https://api.riskmanager.fugue.co/v0/swagger -l ruby -o c:\temp\ruby_api_client

You can find a list of supported languages by executing swagger-codegen (Homebrew version) or java -jar swagger-codegen-cli-2.2.1.jar (other versions).

Authentication

When Fugue creates an API client for an environment, it also generates a Client ID and Client Secret. These values are used to ensure secure communication with Fugue, and they must be passed to the API in the Authorization HTTP header using Basic Authentication.

An API client can access data across all the environments in your organization within Fugue. However, it’s a best practice to create one client for each API use case, giving them a clear name that describes their purpose. This makes rotating generated Client Secrets easier since each application/script can be located easily and updated individually.

Warning

When Fugue creates the client, you may only view the Client Secret once. Store it securely for use in your applications or scripts. You should not reveal the Client Secret publicly. If you lose your secret, or if it becomes compromised, you can revoke it or generate a new one on the Organization Settings page.

Making API Requests

Paths

To interact with the Fugue API, you send a request over HTTP to a specific API path. This is an example path for listing details for all environments in ascending order:

https://api.riskmanager.fugue.co/v0/environments?order_direction=asc

The path above incorporates the following components:

  • Base URL: api.riskmanager.fugue.co/v0

  • Endpoint: /environments

  • Query parameter: order_direction

The path is combined with an HTTP method such as GET, POST, PATCH, or DELETE to form the API request. For example, the operation above uses GET.

Query, Path, and Request Body Parameters

To determine what query, path, or request body parameters you’ll need for a request, check the API Reference, which also includes a complete list of endpoints. For information on formatting parameters, see Parameter Formatting.

Query Parameters, Single and Multiple

Some endpoints have query parameters, which are listed underneath the endpoint’s Request Parameters list in the API Reference.

Query parameters appear in the query string of an endpoint, after the ?, as demonstrated in the example below:

https://api.riskmanager.fugue.co/v0/environments?order_direction=asc

order_direction is a query parameter specifying what order the API response should appear in – in this case, asc (ascending).

To include multiple query parameters, just add an ampersand (&) and the new parameter name and value at the end of the query string. The first query parameter of an endpoint should always have a question mark (?) in front of it, but subsequent query parameters don’t need it. For example, the endpoint below looks at a particular environment (?environment_id=8f14f5db-9d05-421c-8a6b-0000000000) to return a maximum of 50 (&max_items=50) compliance events (&event_type=COMPLIANCE):

https://api.riskmanager.fugue.co/v0/events?environment_id=8f14f5db-9d05-421c-8a6b-0000000000&max_items=50&event_type=COMPLIANCE

If you want to include multiple values for the same query parameter – say, to return compliance and drift events for an environment –you can add an ampersand (&) and repeat the query parameter with the new value. For example, the query string below specifies event_type twice with different values, like so: &event_type=COMPLIANCE&event_type=DRIFT. As in the previous example, the first query parameter (environment_id) follows a question mark:

https://api.riskmanager.fugue.co/v0/events?environment_id=8f14f5db-9d05-421c-8a6b-0000000000&event_type=COMPLIANCE&event_type=DRIFT

For query parameter formatting, see Parameter Formatting.

Path Parameters

Some endpoints have path parameters, denoted by curly braces in the API Reference. In these cases, replace the {variable} with your own information, without the curly braces. For example, this path is for listing AWS IAM permissions needed to scan and enforce given resources:

https://api.riskmanager.fugue.co/v0/metadata/{provider}/permissions

Above, you can substitute {provider} with aws to specify AWS for standard regions or aws_govcloud for AWS GovCloud regions.

For path parameter formatting, see Parameter Formatting.

Request Bodies

Some API requests require a body. For example, if you’re using POST /environments to create an environment, your body might look like this:

{
  "compliance_families": [
    "CIS", "GDPR", "HIPAA"
  ],
  "name": "API Test",
  "provider": "aws",
  "provider_options": {
    "aws": {
      "region": "us-east-1",
      "role_arn": "arn:aws:iam::XXXXXXXXXXXX:role/ FugueRiskManager"
    }
  },
  "scan_interval": 3600,
  "scan_schedule_enabled": "true",
  "survey_resource_types": [
    "AWS.S3.Bucket", "AWS.EC2.Vpc"
  ]
}

Each field above represents a body parameter. See the API Reference to determine which body parameters you’ll need for your request. For body parameter formatting, see Parameter Formatting.

The way to send the body in an API call will depend on what tool you’re using. Here’s an example in curl and an example in Postman.

Environment and Scan IDs as Parameters

For {environment_id} and {scan_id} query, path, or response body parameters, you’ll have to look up the actual IDs.

You can find the environment ID by navigating to your environment within the Fugue UI, then copying the 36-character identifier in the URL (e.g., ffc3aac1-9338-4965-ae30-3a8611111111).

Alternatively, you can retrieve it through the API itself by sending a GET /environments request to retrieve a list of your environments. Here’s the path:

https://api.riskmanager.fugue.co/v0/environments

And here’s the full API request, using curl:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/environments" \
  -u $CLIENT_ID:$CLIENT_SECRET

In the response, look for the id field in each listed environment to locate the ID you need:

{
 "count": 1,
 "is_truncated": false,
 "items": [
   {
     "baseline_id": null,
     "compliance_families": [
       "CIS",
       "PCI"
     ],
     "drift": false,
     "id": "8644d565-10ed-4788-813e-6e5700000000",
     ...
   }
 ]
}

To determine the ID of a particular scan, you can also retrieve it through the API by sending a GET /scans?environment_id={environment_id} request, which returns a list of every scan in the given environment along with scan IDs. The path might look like this:

https://api.riskmanager.fugue.co/v0/scans?environment_id=ffc3aac1-9338-4965-ae30-3a8611111111

And the full API request might look like this, using curl:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/scans?environment_id=ffc3aac1-9338-4965-ae30-3a8611111111" \
  -u $CLIENT_ID:$CLIENT_SECRET

Just like with the environment ID, look for the id field in each listed scan of the response to locate the scan ID you need:

{
  "count": 16,
  "is_truncated": false,
    "items": [
    {
      "created_at": 1553747169,
      "environment_id": "ffc3aac1-9338-4965-ae30-3a8611111111",
      "finished_at": 1553747373,
      "id": "8576a1b3-2f72-4e1d-902a-c81f22222222",
      "message": null,
      "remediation_error": false,
      "status": "SUCCESS",
      "updated_at": 1553747373
    }
  ]
}

Parameter Formatting

To learn how to format query, path, and request body parameters, or to understand response formatting, see Compliance Standards, Resource Types, and Time and Date below. To learn how to find environment and scan IDs, see Environment and Scan IDs.

Compliance Standards

Some operations require you to specify one or more compliance standards in a query or request body parameter:

Here is how to format each supported compliance standard in an API request:

  • "CIS" (for CIS AWS)

  • "CISAZURE"

  • "GDPR"

  • "HIPAA"

  • "ISO27001"

  • "NIST"

  • "PCI"

  • "SOC2"

You can specify the family query parameter multiple times in the query endpoints to retrieve multiple standards. For example, you can use the HTTP GET method with the following endpoint to filter compliance results by the CIS AWS and GDPR compliance standards:

GET /scans/{scan_id}/compliance_by_rules?family=CIS&family=GDPR

Resource Types

To see a list of all supported resource types for a cloud provider, with each resource name formatted the way the API expects it, see Service Coverage.

Note that resource types in request body parameters must be surrounded by double quotes, like "AWS.EC2.Vpc" or "AWS.S3.Bucket". You can specify the resource type multiple times in the body to retrieve multiple standards. For example, if you’re using POST /environments to create an environment and scan only "AWS.EC2.Vpc" and "AWS.S3.Bucket" resources, your body might look like this:

{
  "compliance_families": [],
  "name": "API Example",
  "provider": "aws",
  "provider_options": {
    "aws": {
      "region": "us-east-1",
      "role_arn": "arn:aws:iam::XXXXXXXXXXXX:role/FugueRiskManager"
    }
  },
  "survey_resource_types": [
    "AWS.EC2.Vpc", "AWS.S3.Bucket"
  ]
}

Resource types in query parameters should not use double quotes. You can specify the resource type multiple times in the query endpoints to retrieve multiple standards. For example, this request filters compliance results by AWS.EC2.Vpc and AWS.S3.Bucket resources:

https://api.riskmanager.fugue.co/v0/scans/{scan_id}/compliance_by_resource_types?resource_type=AWS.EC2.Vpc&resource_type=AWS.S3.Bucket

You can also retrieve the list through the API itself by sending a GET /metadata/{provider}/resource_types?region={region} request. The path might look like this, if you’re retrieving resource types supported in the us-gov-west-1 region of the provider aws_govcloud:

https://api.riskmanager.fugue.co/v0/metadata/aws_govcloud/resource_types?region=us-gov-west-1

The full API request might look like this, using curl:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/metadata/aws_govcloud/resource_types?region=us-gov-west-1" \
  -u $CLIENT_ID:$CLIENT_SECRET

The response includes a list of all supported resources for that provider.

Time and Date

Timestamps in API requests and responses are formatted using Unix time (also called Epoch time), which looks like this: 1558964232. To convert a date and time to a Unix timestamp, or vice versa, you can use an online converter such as this one. If you’re using Postman and you want the current time automatically converted to Unix time, simply copy and paste the string {{$timestamp}} into the desired field, as shown below. Postman will convert {{$timestamp}} into Unix time automatically.

_images/UnixTimestampPostman.png

Deep Dives

Baselines, Drift Detection, and Enforcement

The API allows you to update an environment to:

  • Set (enable/update) a baseline, which enables drift detection

  • Disable a baseline and drift detection

  • Enable baseline enforcement (auto-remediation)

  • Disable baseline enforcement

Enabling a baseline and updating a baseline are the same thing, to the API. In both cases, you set the baseline by sending an API request to update your environment with the scan ID you want to use as the baseline in the request body. The infrastructure configuration in that scan becomes the baseline. When you set a baseline, drift detection is also enabled.

Disabling a baseline is a similar process, except instead of providing a scan ID for the baseline, you replace it with an empty string. When you disable a baseline, drift detection is also disabled.

Enabling enforcement and disabling enforcement also involve sending an API request to update your environment. The request body is the only difference, which sets remediation to true or false to enable or disable it.

API Path for Baseline, Drift Detection, and Enforcement Changes

Whether you’re enabling/disabling a baseline, drift detection, or enforcement, you’ll need to find your environment ID and update the environment by sending a request body to the following API path, replacing {environment_id} with your ID:

https://api.riskmanager.fugue.co/v0/environments/{environment_id}

Request Bodies for Baseline, Drift Detection, and Enforcement Changes

When you update an environment, the request body only needs to include the field(s) you want to modify. Anything that isn’t included isn’t changed. This means each example below can be used as a complete request body. However, if you want to change other environment settings at the same time, you can include them in the body as well. For example, you can also update the scan interval. For a full list of fields, see the API Reference.

Set a Baseline & Enable Drift Detection – Request Body

To set (enable/update) a baseline and enable drift detection, find the scan ID you want to use as a baseline and send the following request body to the API path, replacing {scan_id} with your ID. When you set a baseline, drift detection is also enabled.

{
  "baseline_id": "{scan_id}"
}

Because setting and updating a baseline are the same thing to the API, the request enables a baseline if it isn’t already enabled and sets it to the given scan ID.

Disable a Baseline & Drift Detection – Request Body

To disable a baseline and drift detection, send the following request body to the API path, which changes the scan ID to an empty string. When you disable a baseline, drift detection is also disabled.

{
  "baseline_id": ""
}

Enable Enforcement – Request Body

To enable baseline enforcement, send the following request body to the API path:

{
  "remediation": true
}

Disable Enforcement – Request Body

To disable baseline enforcement, send the following request body to the API path:

{
  "remediation": false
}

How to Set/Disable a Baseline & Drift Detection with curl

To set (enable/update) a baseline and enable drift detection with curl, find the scan ID you want to use as a baseline and the environment ID you want to update, then use the following command, replacing {environment_id} and {scan_id} with your IDs. The -d option contains the request body.

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/{environment_id}" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -d '{
    "baseline_id": "{scan_id}"
}'

To disable the baseline and drift detection with curl, use the same command but set "baseline_id" to "" (empty string).

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/{environment_id}" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -d '{
    "baseline_id": ""
}'

How to Enable/Disable Enforcement (Auto-remediation) with curl

To enable baseline enforcement (auto-remediation) with curl, find the environment ID you want to update, then use the following command, replacing {environment_id} with your ID. The -d option contains the request body.

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/{environment_id}" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -d '{
    "remediation": true
}'

To disable baseline enforcement with curl, use the same command but set "remediation" to false.

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/{environment_id}" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -d '{
    "remediation": false
}'

When your curl command successfully completes, the API returns a JSON document containing all of the details for your updated environment.

For more information about using curl, see API Tools.

More curl Examples

This example curl command sets the baseline to the scan ID f9c4fcbc-57e8-4e75-9bfb-b5aa03000000 for environment ID 8f12957b-9aec-40d2-9e4a-000000000000. When you set a baseline, drift detection is also enabled.

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/8f12957b-9aec-40d2-9e4a-000000000000" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -d '{
    "baseline_id": "f9c4fcbc-57e8-4e75-9bfb-b5aa03000000"
}'

This curl command disables the baseline, drift detection, and enforcement for environment ID b671652f-35c1-4b5d-92ea-000000000000. When you disable a baseline, drift detection is also disabled.

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/b671652f-35c1-4b5d-92ea-000000000000" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -d '{
    "baseline_id": "",
    "remediation": false
}'

When the curl command succeeds, the API returns a JSON document containing all of the details for your updated environment.

For more information about using curl, see API Tools.

Making Baseline Changes with Postman

To make any baseline change with Postman, follow these steps:

1. First, find the environment ID you want to update.

2. In Postman, select the PATCH - Updates an environment request from the Fugue API collection and paste your environment ID into the environment_id field:

_images/PostmanUpdateEnv.png

3. Next, select the “Body” tab:

_images/PostmanUpdateInterval1.png

4. Enter the request body for the desired baseline change in the form below the “Body” tab. If you’re setting a baseline, you’ll need to find the scan ID you want to use as a baseline.

As an example, this request body disables the baseline:

{
  "baseline_id": ""
}

This example request body updates a baseline and enables drift detection by setting the baseline ID to 366cc170-1fec-426f-bf90-10cf00000000. It also enables enforcement:

{
  "baseline_id": "366cc170-1fec-426f-bf90-10cf00000000",
  "remediation": true
}

5. When you’re ready, hit the “Send” button, and when the request succeeds you’ll see a 200 OK status and a JSON document containing all of the details for your updated environment.

For more information about using Postman, see API Tools.

Updating a Scan Interval

The API allows you to change the scan interval for an environment by updating the environment. The default scan interval is 1 day and is specified in seconds, so the default value is 86400.

When Scan Interval Changes Take Effect

Scan interval changes take effect immediately, so the next scan occurs after the new interval. Say it’s noon and you change the scan interval from 12 hours to 1 hour. The next scan takes place 1 hour after you set the interval, at 1 p.m.

Likewise, if it’s noon and you change the interval from 12 hours to 1 day, the next scan occurs at noon the next day.

You can still manually trigger a scan at any time if you want your environment scanned sooner.

API Path for Changing the Scan Interval

The API path for changing the scan interval is the same API path for changing the baseline, drift detection, and enforcement. This is because the operations all require you to update fields in your environment.

To update the scan interval, you’ll need to find your environment ID and update the environment by sending a request body to the following API path, replacing {environment_id} with your ID:

https://api.riskmanager.fugue.co/v0/environments/{environment_id}

Request Body for Updating a Scan Interval

To update the scan interval, send the following request body to the API path, replacing {interval_in_seconds} with the desired length of time:

{
  "scan_interval": "{interval_in_seconds}"
}

When you update an environment, the request body only needs to include the field(s) you want to modify. Anything that isn’t included isn’t changed. This means the example above can be used as a complete request body. However, if you want to change other environment settings at the same time, you can include them in the body as well. For example, you can also make changes to baselines, drift detection, and enforcement (auto-remediation). For a full list of fields, see the API Reference.

Updating the Scan Interval with curl

This example curl command updates the scan interval to 14,400 seconds (4 hours) for environment 8f12957b-9aec-40d2-9e4a-000000000000:

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/8f12957b-9aec-40d2-9e4a-000000000000" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -d '{
    "scan_interval": "14400"
}'

When the curl command succeeds, the API returns a JSON document containing all of the details for your environment, including the updated scan interval.

For more information about using curl, see API Tools.

Updating the Scan Interval with Postman

To update the scan interval using Postman, you’ll follow the same steps you would use to make baseline changes, but in Step 4, enter the scan interval request body into the form below the “Body” tab instead. As an example, this request body changes the scan interval to 4 hours (14,400 seconds):

{
  "scan_interval": "14400"
}

When you’re ready, hit the “Send” button, and when the request succeeds you’ll see a 200 OK status and a JSON document listing all of the details for your environment, including the updated scan interval.

For more information about using Postman, see API Tools.

When the Scan Interval Starts Ticking

The scan interval starts over when Fugue ends a scan. It also starts over when you update the scan interval.

Suppose you have a scan interval of 30 minutes and Fugue starts Scan 1 at 12:00. If Fugue finishes Scan 1 at 12:03, Fugue will start Scan 2 at 12:33, 30 minutes later.

Likewise, if it’s noon and you change the interval from 30 minutes to 1 hour, the next scan takes place 1 hour after you set the interval, at 1 p.m.

Initiating a Scan

The API allows you to manually initiate an environment scan whenever you like. To manually trigger a scan, you’ll need to send an API request to create a new scan.

Initiating a Scan with curl

To initiate a scan using curl, send a request to the following path using the POST HTTP method, replacing {environment_id} with your own environment ID:

https://api.riskmanager.fugue.co/v0/scans?environment_id={environment_id}

The full API request might look like this:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/scans?environment_id=b671652f-35c1-4b5d-92ea-000000000000" \
  -u $CLIENT_ID:$CLIENT_SECRET

When the command successfully completes, the API returns a JSON document with the scan ID, status IN_PROGRESS, and other details.

For more information about using curl, see API Tools.

Initiating a Scan with Postman

To initiate a scan using Postman, send a request to the following path using the POST - Creates and triggers a new environment scan request from the Fugue API Postman collection, then paste your environment ID into the environment_id field:

_images/PostmanCreateScan.png

Then, hit the “Send” button, and when the request succeeds you’ll see a 201 Created status and a JSON document listing the scan ID, status IN_PROGRESS, and other details.

For more information about using Postman, see API Tools.

API Tools

You can communicate with Fugue through your preferred API tool, such as curl or Postman.

curl

Curl is a command-line tool that can transfer data over HTTP and is frequently used to interact with APIs. Here’s an example of a curl command that requests the Fugue API to delete an environment:

curl -X DELETE \
"https://api.riskmanager.fugue.co/v0/environments/ffc3aac1-9338-4965-ae30-3a8611111111" \
  -u $CLIENT_ID:$CLIENT_SECRET

For requests that require a body, the easiest way to send it in curl is to paste the body into a JSON file and then use the -d data flag. For example, the following command requests the API to update an environment:

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/{environment}" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

For more information, see the curl manual.

Postman

Postman is a popular GUI for interacting with APIs. You can import Fugue’s API requests as a Postman collection by selecting the File menu, then Import....

_images/APIImportSwagger.png

Next, select the Import From Link tab and paste the Swagger link:

https://api.riskmanager.fugue.co/v0/swagger

Postman will create a collection populated with all of Fugue’s endpoints.

To use Postman to delete an environment, select DEL Deletes an environment from the collection in the sidebar. Then, fill in the details:

In the Params tab:

  • Replace {{environment_id}} with your environment ID.

_images/APIPostmanDelete.png

Next, you’ll need to configure authentication at the Fugue API collection level. This allows each request in the collection to inherit your Client ID and Client Secret. Select the ... button in the Fugue API collection and then select Edit.

_images/APIPostmanEditCollection.png

In the Authorization tab:

  • Set Type to Basic Auth.

  • Set Username to your Client ID.

  • Set Password to your Client Secret.

  • Select the Update button.

_images/APIPostmanAuthCollection.png

Finally, hit the Send button.

Postman will display the response, which in this case is a 204 No Content status without a body.

_images/APIPostmanDeleteResponse.png

Note that if your request requires a body, there’s an extra step. In the Body tab you’ll need to replace the request description with your JSON input. For example, if you’re using PATCH /environments/{environment} to update an environment, your body might look like this:

{
  "compliance_families": [
    "PCI", "NIST"
  ],
  "name": "API Test",
  "provider": "aws",
  "provider_options": {
    "aws": {
      "role_arn": "arn:aws:iam::XXXXXXXXXXXX:role/FugueRiskManager"
    }
  },
  "scan_interval": 7200,
  "scan_schedule_enabled": "true",
  "survey_resource_types": [
    "AWS.SNS.Topic", "AWS.SQS.Queue"
  ]
}

Examples

Below are curl examples of every operation supported by the Fugue API. For general Postman instructions, see Postman.

Some examples below have query, path, and/or request body parameters. To learn more about how parameters are used, see Query Parameters, Single and Multiple; Path Parameters; and Request Bodies. See also Making API Requests to learn the basics of API requests.

Listing Details for All Environments

To list details for all environments, send a GET request to this endpoint:

https://api.riskmanager.fugue.co/v0/environments

Here’s an example curl command that lists details for all environments and uses the query parameter max_items to return a maximum of 100 items:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/environments?max_items=100" \
  -u $CLIENT_ID:$CLIENT_SECRET

Creating an Environment

Before you send an API request to create an environment, see the Azure prerequisites or AWS or AWS GovCloud prerequisites.

To create an environment, send a POST request to this endpoint:

https://api.riskmanager.fugue.co/v0/environments

Send the desired environment settings in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/environments" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

See example request bodies below.

Create Azure Environment - Example Request Body

{
  "name": "Azure Dev",
  "provider": "azure",
  "provider_options": {
    "azure": {
      "tenant_id": "83ad8c73-5f20-4172-4321-000000000000",
      "subscription_id": "20a3dcf5-ce6c-42fa-2ab1-000000000000",
      "application_id": "7caf2fea-725f-49cc-f4c2-000000000000",
      "client_secret": "-b/-6oTtKT*cUQBq0000000000000000",
      "survey_resource_groups": [
        "example-rg",
        "another-rg"
      ]
    }
  },
  "compliance_families": [
    "CISAZURE"
  ],
  "scan_schedule_enabled": true,
  "scan_interval": 43200
}

Create AWS Environment - Example Request Body

{
  "name": "AWS Prod",
  "provider": "aws",
  "provider_options": {
    "aws": {
      "region": "us-east-1",
      "role_arn": "arn:aws:iam::XXXXXXXXXXXX:role/FugueRiskManager"
    }
  },
  "compliance_families": [
    "SOC2",
    "PCI"
  ],
  "survey_resource_types": [
    "AWS.DynamoDB.Table",
    "AWS.EC2.SecurityGroup",
    "AWS.EC2.Vpc",
    "AWS.S3.Bucket"
  ],
  "remediate_resource_types": [
    "AWS.EC2.SecurityGroup",
    "AWS.S3.Bucket"
  ],
  "scan_schedule_enabled": true,
  "scan_interval": 86400
}

Create AWS GovCloud Environment - Example Request Body

{
  "name": "AWS GovCloud Dev",
  "provider": "aws_govcloud",
  "provider_options": {
    "aws_govcloud": {
      "region": "us-gov-west-1",
      "role_arn": "arn:aws-us-gov::iam::XXXXXXXXXXXX:role/FugueRiskManager"
    }
  },
  "compliance_families": [
    "NIST",
    "HIPAA",
    "CIS"
  ],
  "survey_resource_types": [
    "AWS.EC2.SecurityGroup",
    "AWS.EC2.Vpc",
    "AWS.IAM.AccessKey",
    "AWS.IAM.AccountPasswordPolicy"
  ],
  "remediate_resource_types": [
    "AWS.EC2.SecurityGroup"
  ],
  "scan_schedule_enabled": true,
  "scan_interval": 86400
}

Prerequisites for Creating an Azure Environment

Before you can create an Azure environment through the API, Fugue needs permission to scan and/or enforce your Azure resources. If you haven’t done this yet, follow Setup - Azure instructions to create an Active Directory application, assign it a role, and generate a client secret. If Fugue is already connected to your Azure subscription, you can reuse the application ID, though we recommend you create a new client secret.

Prerequisites for Creating an AWS or AWS GovCloud Environment

Before you create an AWS or AWS GovCloud environment through the API, Fugue needs permission to scan and/or enforce your AWS resources. If you haven’t done this yet, or if you have but want different permissions, follow the Setup - AWS instructions to manually create an IAM role. Then, paste the ARN into the role_arn field in the JSON body.

Tip

Use the Fugue API to generate the IAM role policy. For details, see Listing IAM Permissions Required to Scan/Enforce Resources.

Alternatively, if you’ve already created an IAM role with the permissions you want, you can simply reuse the role ARN.

Retrieving Details for a Single Environment

To list details for a particular environment, send a GET request to this endpoint and replace {environment_id} with your environment ID:

https://api.riskmanager.fugue.co/v0/environments/{environment_id}

Here’s an example curl command that lists details for environment b5d68e32-d44e-487e-a21c-123456789012:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/environments/b5d68e32-d44e-487e-a21c-123456789012" \
  -u $CLIENT_ID:$CLIENT_SECRET

Updating an Environment

There are two important things to know about updating an environment.

  • When you update an environment, the request body only needs to include the field(s) you want to modify. Anything that isn’t included isn’t changed. For a full list of fields, see the API Reference.

  • If you want to update a list of properties, you need to include all members of the list in the request body. For example, if your environment is set up with GDPR and ISO27001 and you want to add NIST, you would include all three as shown in the example below in Update Compliance Families - Example Request Body.

To update an environment, send a PATCH request to this endpoint and replace {environment_id} with your environment ID:

https://api.riskmanager.fugue.co/v0/environments/{environment_id}

Send the settings you want to update in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/environments/b5d68e32-d44e-487e-a21c-123456789012" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

See example request bodies below.

Update AWS Compliance Families - Example Request Body

{
  "compliance_families": [
    "GDPR",
    "ISO27001",
    "NIST"
  ]
}

Update Scanned Azure Resource Groups - Example Request Body

{
    "provider": "azure",
    "provider_options": {
        "azure": {
            "survey_resource_groups": [
                "prod-centralus",
                "dev-centralus",
                "dev-eastus"
            ]
        }
    }
}

Set Baseline and Scan Interval - Example Request Body

To the API, enabling a baseline and updating it are the same process (also called setting a baseline). In both cases you’ll need find the scan ID you want use as a baseline. For more information about baselines and the API, see Baselines, Drift Detection, and Enforcement.

{
  "baseline_id": "0018c15e-3384-45a0-89f9-f5e0c1cf30d7",
  "scan_interval": 86400
}

Deleting an Environment

To delete an environment, send a DELETE request to this endpoint and replace {environment_id} with your environment ID:

https://api.riskmanager.fugue.co/v0/environments/{environment_id}

Here’s an example curl command that deletes environment b5d68e32-d44e-487e-a21c-123456789012:

curl -X DELETE \
"https://api.riskmanager.fugue.co/v0/environments/b5d68e32-d44e-487e-a21c-123456789012" \
  -u $CLIENT_ID:$CLIENT_SECRET

Listing Scans for an Environment

To list scans for an environment, send a GET request to this endpoint and replace {environment_id} with your environment ID:

https://api.riskmanager.fugue.co/v0/scans?environment_id={environment_id}

Here’s an example curl command that retrieves a list of all scans for environment f078721c-f859-4abf-8589-555555555555 that have completed successfully (status=SUCCESS) since noon EDT on July 21, 2019 (range_from=1563667200 – see Unix time):

curl -X GET \
"https://api.riskmanager.fugue.co/v0/scans?environment_id=f078721c-f859-4abf-8589-555555555555&status=SUCCESS&range_from=1563667200" \
  -u $CLIENT_ID:$CLIENT_SECRET

Triggering a New Scan

To initiate a scan for an environment, send a POST request to this endpoint and replace {environment_id} with your environment ID:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/scans?environment_id={environment_id}"

Here’s an example curl command that triggers a scan for environment f078721c-f859-4abf-8589-555555555555:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/scans?environment_id=f078721c-f859-4abf-8589-555555555555" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more about manually triggering scans, see Initiating a Scan.

Retrieving Details for a Scan

To list details for a particular scan, send a GET request to this endpoint and replace {scan_id} with your scan ID:

https://api.riskmanager.fugue.co/v0/scans/{scan_id}

Here’s an example curl command that lists details for scan 1a6c79d0-113d-43c6-87e4-098765432109:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/scans/1a6c79d0-113d-43c6-87e4-098765432109" \
  -u $CLIENT_ID:$CLIENT_SECRET

Listing Compliance Results by Rule for a Scan

To list compliance results by rule for a particular scan, send a GET request to this endpoint and replace {scan_id} with your scan ID:

https://api.riskmanager.fugue.co/v0/scans/{scan_id}/compliance_by_rules

Here’s an example curl command that lists compliance results from scan 1a6c79d0-113d-43c6-87e4-098765432109 for PCI and SOC 2 (?family=PCI&family=SOC2):

curl -X GET \
"https://api.riskmanager.fugue.co/v0/scans/1a6c79d0-113d-43c6-87e4-098765432109/compliance_by_rules?family=PCI&family=SOC2" \
  -u $CLIENT_ID:$CLIENT_SECRET

Listing Compliance Results by Resource Type for a Scan

To list compliance results by resource types for a particular scan, send a GET request to this endpoint and replace {scan_id} with your scan ID:

https://api.riskmanager.fugue.co/v0/scans/{scan_id}/compliance_by_resource_types

Here’s an example curl command that lists compliance results for only VPCs and S3 buckets (?resource_type=AWS.EC2.Vpc&resource_type=AWS.S3.Bucket) from scan 1a6c79d0-113d-43c6-87e4-098765432109 for all compliance families. (When a family or resource_type parameter is not specified, results include all compliance families and resource types, respectively.)

curl -X GET \
"https://api.riskmanager.fugue.co/v0/scans/1a6c79d0-113d-43c6-87e4-098765432109/compliance_by_resource_types?resource_type=AWS.EC2.Vpc&resource_type=AWS.S3.Bucket" \
  -u $CLIENT_ID:$CLIENT_SECRET

Note

The endpoint uses the plural compliance_by_resource_types, and the query parameter is singular, resource_type.

Listing Compliance/Drift/Remediation Events for an Environment

To list compliance, drift, and remediation events for a particular environment, send a GET request to this endpoint and replace {environment_id} with your scan ID:

https://api.riskmanager.fugue.co/v0/events?environment_id={environment_id}

Here’s an example curl command that looks at environment f078721c-f859-4abf-8589-555555555555 for all drift events and only successful remediation events. (When an event_type, change, resource_type, or remediated parameter is not specified, results include all events, all types of drift changes, all resource types, or success or failure of all remediation events, respectively.)

curl -X GET \
"https://api.riskmanager.fugue.co/v0/events?environment_id=f078721c-f859-4abf-8589-555555555555&event_type=DRIFT&event_type=REMEDIATION&remediation=SUCCESS" \
  -u $CLIENT_ID:$CLIENT_SECRET

Note

event_type=REMEDIATION refers to events in which Fugue attempted to auto-remediate (enforce) a drifted resource. In contrast, remediation={status} refers to events in which such an attempt succeeded or failed.

Returning Fugue’s OpenAPI 2.0 Specification

To return the Fugue API’s OpenAPI 2.0 Specification (swagger.yaml), send a GET request to this endpoint:

https://api.riskmanager.fugue.co/v0/swagger

Here’s an example curl command that returns the OpenAPI 2.0 spec:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/swagger" \
  -u $CLIENT_ID:$CLIENT_SECRET

You can also see the user-friendly OpenAPI 2.0 spec in the API Reference. To access an interactive version, see the Swagger UI.

Listing IAM Permissions Required to Scan/Enforce Resources

To list the required IAM permissions for scanning and remediating (enforcing) AWS or AWS GovCloud resources, send a POST request to this endpoint and replace {provider} with either aws or aws_govcloud. You can find a list of supported resource types in the Service Coverage or through the Listing Supported Resource Types.

https://api.riskmanager.fugue.co/v0/metadata/{provider}/permissions

Send the AWS or AWS GovCloud resources you want Fugue to scan or auto-remediate (enforce) in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/metadata/aws_govcloud/permissions" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

The API response contains a generated IAM policy you can use when manually creating a role.

See example request bodies below.

Note

This operation is not necessary or supported for Azure environments. To learn more, see Setup - Azure.

Return AWS IAM Permissions - Example Request Body

{
  "survey_resource_types": [
    "AWS.DynamoDB.Table",
    "AWS.EC2.SecurityGroup",
    "AWS.EC2.Vpc",
    "AWS.S3.Bucket",
    "AWS.WAF.WebACL"
  ],
  "remediate_resource_types": [
    "AWS.EC2.SecurityGroup",
    "AWS.S3.Bucket"
  ]
}

Return AWS GovCloud IAM Permissions - Example Request Body

{
  "survey_resource_types": [
    "AWS.CloudTrail.Trail",
    "AWS.IAM.AccessKey",
    "AWS.IAM.AccountPasswordPolicy",
    "AWS.IAM.GroupMembership"
  ]
}

Listing Supported Resource Types

To list a provider’s supported resource types, send a GET request to this endpoint and replace the following parameters:

  • Replace {provider} with either aws or aws_govcloud

  • Replace {region} with the AWS or AWS GovCloud region

https://api.riskmanager.fugue.co/v0/metadata/{provider}/resource_types?region={region}

Here’s an example curl command that lists all the AWS resource types Fugue supports:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/metadata/aws/resource_types?region=us-east-1" \
  -u $CLIENT_ID:$CLIENT_SECRET

Listing Details for All Notifications

To list details for all notifications, send a GET request to this endpoint:

https://api.riskmanager.fugue.co/v0/notifications

Here’s an example curl command that lists details for a maximum of 5 notifications (?max_items=5) in an organization:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/notifications?max_items=5" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more, see Notifications.

Creating a Notification

To create a notification, send a POST request to this endpoint:

https://api.riskmanager.fugue.co/v0/notifications

Send the desired environment settings in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/notifications" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

See example request bodies below.

If you want a notification to use a manually created SNS topic, update the topic’s access policy with this access policy. To learn more, see Notifications.

Create Email Notification for All Events - Example Request Body

{
  "name": "Example Notification - All, SNS/Email",
  "events": [
    "compliance",
    "drift",
    "remediation"
  ],
  "environments": [
    "8f12957b-9aec-40d2-9e4a-000000000000"
  ],
  "emails": [
    "username@email.com",
    "anotheruser@email.com"
  ],
  "topic_arn": "arn:aws:sns:us-east-1:XXXXXXXXXXXX:FugueSNSTopic"
}

Create Email & SNS Notification for Drift - Example Request Body

{
  "name": "Example Notification - Drift, Email",
  "events": [
    "drift"
  ],
  "environments": [
    "8f12957b-9aec-40d2-9e4a-000000000000",
    "ffc3aac1-9338-4965-ae30-3a8600000000"
  ],
  "emails": [
    "username@email.com"
  ]
}

Updating a Notification

Updating an existing notification overwrites the current settings, which means you need to include all of the original fields in addition to the modified fields in your JSON request body. This is because the operation uses the PUT method. The process differs from updating an environment, which uses the PATCH method and allows you to omit fields that aren’t being changed. For a full list of notification properties, see the API Reference.

To update a notification, send a PUT request to this endpoint and replace {notification_id} with your notification ID, which you can find in the notification details:

https://api.riskmanager.fugue.co/v0/notifications/{notification_id}

Send the settings you want to update in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X PUT \
"https://api.riskmanager.fugue.co/v0/notifications/13906fc2-e6d2-4b4f-948f-121212121212" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

See example request bodies below.

If you want a notification to use a manually created SNS topic, update the topic’s access policy with this access policy. To learn more, see Notifications.

Add Environments to Notification - Example Request Body

{
  "name": "Updated Notification - All, SNS/Email",
  "events": [
    "compliance",
    "drift",
    "remediation"
  ],
  "environments": [
    "8f12957b-9aec-40d2-9e4a-000000000000",
    "ffc3aac1-9338-4965-ae30-3a8600000000",
    "b5d68e32-d44e-487e-a21c-123456789012",
    "f078721c-f859-4abf-8589-555555555555"
  ],
  "emails": [
    "username@email.com",
    "anotheruser@email.com"
  ],
  "topic_arn": "arn:aws:sns:us-east-1:XXXXXXXXXXXX:FugueSNSTopic"
}

Listing Details for All Notifications

To list details for all notifications, send a GET request to this endpoint:

https://api.riskmanager.fugue.co/v0/notifications

Here’s an example curl command that lists details for a maximum of 5 notifications (?max_items=5) in an organization:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/notifications?max_items=5" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more, see Notifications.

Deleting a Notification

To delete a notification, send a DELETE request to this endpoint:

https://api.riskmanager.fugue.co/v0/notifications/{notification_id}

Here’s an example curl command that deletes notification 13906fc2-e6d2-4b4f-948f-121212121212:

curl -X DELETE \
"https://api.riskmanager.fugue.co/v0/notifications/13906fc2-e6d2-4b4f-948f-121212121212" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more, see Notifications.

Creating a Custom Rule

To create a custom rule, send a POST request to this endpoint:

https://api.riskmanager.fugue.co/v0/rules

Send the desired custom rule settings in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/rules" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

See example request bodies below. To learn more, see Custom Rules.

Create Custom Rule for Azure - Example Request Body

{
  "name": "Azure VMs should be in availability sets",
  "source": "CUSTOM",
  "description": "Azure Virtual Machines should be in availability sets. Deploying VMs in availability sets promotes redundancy of data.",
  "provider": "Azure",
  "resource_type": "Azure.Compute.VirtualMachine",
  "rule_text": "allow { startswith(input.availability_set_id, '/') }"
}

Create Custom Rule for AWS GovCloud - Example Request Body

{
  "name": "AWS RDS instances should have multi-AZ enabled",
  "source": "CUSTOM",
  "description": "An RDS instance in a Multi-AZ (availability zone) deployment provides enhanced availability and durability of data.",
  "provider": "AWS_GOVCLOUD",
  "resource_type": "AWS.RDS.Instance",
  "rule_text": "allow { input.multi_az == true }"
}

Listing Custom Rules

To list all custom rules, send a GET request to this endpoint:

https://api.riskmanager.fugue.co/v0/rules

Here’s an example curl command that lists all custom rules for an organization:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/rules" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more, see Custom Rules.

Retrieving Details for a Rule

To retrieve details for a particular rule, send a GET request to this endpoint and replace {rule_id} with your rule ID, which you can find in the list of custom rules:

https://api.riskmanager.fugue.co/v0/rules/{rule_id}

Here’s an example curl command that lists details for rule c2ace21a-a52d-4da2-934c-098765432109:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/rules/c2ace21a-a52d-4da2-934c-098765432109" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more, see Custom Rules.

Updating a Custom Rule

When you update a custom rule, the request body only needs to include the field(s) you want to modify. Anything that isn’t included isn’t changed. For a full list of fields, see the API Reference.

To update a custom rule, send a PATCH request to this endpoint and replace {rule_id} with your rule ID, which you can find in the list of custom rules:

https://api.riskmanager.fugue.co/v0/rules/{rule_id}

Send the settings you want to update in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X PATCH \
"https://api.riskmanager.fugue.co/v0/rules/c2ace21a-a52d-4da2-934c-098765432109" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

See example request body below. To learn more, see Custom Rules.

Update Rule Text - Example Request Body

{
   "rule_text": "allow { startswith(input.availability_set_id, '/') }"
}

Deleting a Custom Rule

To delete a custom rule, send a DELETE request to this endpoint and replace {rule_id} with your rule ID, which you can find in the list of custom rules:

https://api.riskmanager.fugue.co/v0/rules/{rule_id}

Here’s an example curl command that deletes rule c2ace21a-a52d-4da2-934c-098765432109:

curl -X DELETE \
"https://api.riskmanager.fugue.co/v0/rules/c2ace21a-a52d-4da2-934c-098765432109" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more, see Custom Rules.

Testing a Custom Rule

To test a custom rule using state from a scan, send a POST request to this endpoint:

https://api.riskmanager.fugue.co/v0/rules/test

Send the desired custom rule settings in the JSON request body. You can save the JSON in a file and attach it with the -d @{filename} option:

curl -X POST \
"https://api.riskmanager.fugue.co/v0/rules/test" \
  -u $CLIENT_ID:$CLIENT_SECRET \
  -H "Content-Type: application/json" \
  -d @body.json

See example request body below. To learn more, see Custom Rules.

Test Rule Against Scan State - Example Request Body

{
    "rule_text": "allow { startswith(input.availability_set_id, '/') }",
    "scan_id": "535d21d2-700b-4b4f-9aa9-123456789012",
    "resource_type": "Azure.Compute.VirtualMachine"
}

Getting Input for a Custom Rule Test

To get the input for a custom rule test, send a GET request to this endpoint and replace {scan_id} with the scan ID whose state you want to return:

https://api.riskmanager.fugue.co/v0/rules/test/input?scan_id={scan_id}

Here’s an example curl command that returns the state of the infrastructure recorded in scan 535d21d2-700b-4b4f-9aa9-123456789012 so you can then test a rule against it:

curl -X GET \
"https://api.riskmanager.fugue.co/v0/rules/test/input?scan_id=535d21d2-700b-4b4f-9aa9-123456789012" \
  -u $CLIENT_ID:$CLIENT_SECRET

To learn more, see Custom Rules.

Further Reading

To learn more about the API, reach out to support@fugue.co. If you’d like to see the full human-readable API documentation with examples, visit the API Reference. To access an interactive version of the Swagger spec, see the Swagger UI. Or, you can access the Swagger specification file directly here.