API Request 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 with Multiple Regions - Example Request Body

{
  "name": "AWS Prod",
  "provider": "aws",
  "provider_options": {
    "aws": {
      "regions": [
          "us-west-1",
          "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": {
      "regions": [
          "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 steps in How To: Manually Create a Fugue IAM Role 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.

For a list of all possible IAM permissions, see AWS IAM Policy Permissions.

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 three 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.

  • Regions can be updated for certain environments only. The environment must be configured with the regions parameter rather than region. See details here.

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"
            ]
        }
    }
}

Update AWS GovCloud Regions - Example Request Body

Only certain environments support region updates. See details here.

{
    "provider_options": {
        "aws_govcloud": {
            "regions": [
                "us-gov-west-1",
                "us-gov-east-1"
            ]
        }
    }
}

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 Control for a Scan

To list compliance results by control 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/Baseline Enforcement Events for an Environment

To list compliance, drift, and baseline enforcement 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 baseline enforcement 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 enforcement 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 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 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 Service Coverage - AWS & AWS GovCloud or through Listing Supported Resource Types. For a list of all possible IAM permissions, see AWS IAM Policy Permissions.

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

Send the AWS or AWS GovCloud resources you want Fugue to scan or 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

{
    "resource_type": "Azure.Compute.VirtualMachine",
    "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

  • Learn the basics of using the API, including how to send requests, in the API User Guide.

  • If you’d like to see the full human-readable API documentation (Swagger spec), 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.