Skip to content
A tool for integrating with Imperva Cloud API Security
Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE.md
README.md

README.md

Imperva Cloud API Security Integration

Imperva Cloud API Security Integration is a tool that provides easy integration with the Imperva API Security solution to protect APIs that are managed with different API management platforms.

The tool includes predefined integrations with the following API management platforms:

  • Red Hat 3scale API Management
  • Microsoft Azure API Management
  • Amazon API Gateway

In addition, the tool includes the ability to integrate with a local filesystem, and supports adding more integrations.

Requirements

python 3.5.0 or higher

Configuration

In order to run the tool, you need to provide a configuration in JSON format. The configuration contains the following sections:

  • Imperva Management Settings
  • Logging Settings
  • API Fetchers Settings

Imperva Management Settings

Field Description
management_url The Imperva API Security URL
api_id The API ID for the Imperva management console
api_key The API Key for the Imperva management console
site_id The Imperva Cloud WAF site ID
default_action The API Specification Violation Action. Valid values are "ALERT_ONLY", "BLOCK_REQUEST", "BLOCK_USER", "BLOCK_IP", "IGNORE"

For example:

{
    "management_url":"https://api.imperva.com/api-security/api/",
    "api_id":"12345",
    "api_key":"abcd1234",
    "site_id":"123456789",
    "default_action":"BLOCK_REQUEST"
}

Logging Settings

Field Description
status_path Sets the directory location for reporting the integration run status when it is finished. If left empty, the status will not be written to a file
log_path Sets the directory location for the tool logging. If left empty, the log will not be written to a file
level Sets the log level. Valid values are "DEBUG", "INFO" and "ERROR"

For example:

{
    "logging":{
        "status_path":"/var/log/imperva/cloud-api-security",
        "log_path":"/var/log/imperva/cloud-api-security",
        "level":"INFO"
    }
}

API Fetchers Settings

Field Description
type The fetcher type - should be the name of the Python class name of the fetcher
active Boolean which indicates if the fetcher is active or not
settings A JSON of the fetcher settings

Filesystem Fetcher Settings

Field Description
filesystem_path The filesystem path for the API specification files

Example:

{
  "type":"FileSystemFetcher",
  "active":true,
  "settings":{
    "filesystem_path":"/etc/imperva/cloud-api-security/apis"
  }
}

Red Hat 3Scale API Management

Field Description
three_scale_url The URL to the 3Scale API management
three_scale_access_token The 3Scale access token. To generate an access token, see the 3Scale documentation

Example:

{
  "type":"ThreeScaleFetcher",
  "active":true,
  "settings":{
    "three_scale_url":"my-apis-for-imperva.3scale.net",
    "three_scale_access_token":"abcd1234"
  }
}

Microsoft Azure API Management

The integration is based on the Azure API Management REST API. To enable it, see the Azure documentation

Field Description
subscription_id The subscription ID
resource_group_name The name of the resource group
service_name The service name
access_token The Azure API Management REST API access token. To generate one, see the documentation

Example:

{
  "type":"AzureFetcher",
  "active":true,
  "settings":{
    "subscription_id":"1234",
    "resource_group_name":"abcd1234",
    "service_name":"abcd",
    "access_token":"SharedAccessSignature abcd1234"
  }
}

Amazon API Gateway

In order to integrate with AWS we use Boto3, which is the AWS SDK for Python. An installation is required as described in this documentation, and can be done by running:

pip install boto3
Field Description
aws_access_key_id The access key for your AWS account
aws_secret_access_key The secret key for your AWS account
aws_region The AWS region

Example:

{
  "type":"AwsApiGwFetcher",
  "active":true,
  "settings":{
    "aws_access_key_id":"1234",
    "aws_secret_access_key":"abcd1234",
    "aws_region":"eu-west-1"
  }
}

Full settings JSON example:

{
  "logging":{
    "status_path":"/var/log/imperva/cloud-api-security",
    "log_path":"/var/log/imperva/cloud-api-security",
    "level":"DEBUG"
  },
  "api_id":"12345",
  "api_key":"abcd1234",
  "site_id":"123456789",
  "management_url":"https://api.imperva.com/api-security/api/",
  "default_action":"BLOCK_REQUEST",
  "fetchers":[
    {
      "type":"FileSystemFetcher",
      "active":true,
      "settings":{
        "filesystem_path":"/etc/imperva/cloud-api-security/apis"
      }
    },
    {
      "type":"ThreeScaleFetcher",
      "active":true,
      "settings":{
        "three_scale_url":"my-apis-for-imperva.3scale.net",
        "three_scale_access_token":"abcd1234"
      }
    },
    {
      "type":"AzureFetcher",
      "active":true,
      "settings":{
        "subscription_id":"1234",
        "resource_group_name":"abcd1234",
        "service_name":"abcd",
        "access_token":"SharedAccessSignature abcd1234"
      }
    },
    {
      "type":"AwsApiGwFetcher",
      "active":true,
      "settings":{
        "aws_access_key_id":"1234",
        "aws_secret_access_key":"abcd1234",
        "aws_region":"eu-west-1"
      }
    }
  ]
}

Running

In order to run the integration, you need to provide the configuration as a file location or directly as a JSON string.

To run with a configuration file use:

python3 ApiSecurityManager.py -p <path_to_config_file>

To run directly with a configuration JSON use:

python3 ApiSecurityManager.py -c {"the configuration json"}

Note that if no parameter is passed, the default file location is /etc/imperva/cloud-api-security/config/config.json.

You can always run the following to get help information:

python3 ApiSecurityManager.py -h

Status

At the end of the run, the tool returns a numeric status which indicates if the run had errors, or if it was fully successful. For a fully successful run, a zero value (0) is returned. For any run were an error occurred, a non-zero value is returned.

In addition, a full status report in JSON format is provided. The status report is printed into the log, and if a file path is provided in the configuration JSON (status_path in the logging section), the status report will be written to there with a file named status.json.

The status report JSON structure is as follows:

Field Description
time The execution end time (epoch in milliseconds)
has_errors True if there were errors, otherwise false
apis An object with three object values - "added", "updated", and "deleted". Each object contains two list - "success" and "error", of APIs according to the action and if it was successful or not
fetchers An object containing two lists - "success" and "error" of fetchers according to if the tool managed to fetch APIs from them

Example:

{
    "time": 1554374853797, 
    "has_errors": true, 
    "apis": {
        "added": {
            "success":["api-123.example.com/api1", "api-123.example.com/api2"],
            "error": ["api.my-site.com/api"]
        }, 
        "updated": {
            "success": ["api-portal.myportal.com/store"],
            "error": []
        }, 
        "deleted": {
            "success": ["api-portal.myportal.com/partners-api"],
            "error": []
        }
    }, 
    "fetchers": {
        "success": ["ThreeScaleFetcher", "AzureFetcher", "AwsApiGwFetcher"],
        "error": ["FileSystemFetcher"]
    }
}

Getting Help

If you have questions about the library, be sure to check out the source code documentation. If you still have questions, reach out to me via email at doron.lehmann@imperva.com.

Reporting Bugs

Open a Git Issue and include as much information as possible. If possible, provide sample code that illustrates the problem you're encountering. If you're experiencing a bug on a specific repository only, provide a link to it, if possible. Do not open a Git Issue for help, leave it only for bug reports.

You can’t perform that action at this time.