Skip to main content

Network reputation (user override) (TCA-0408)

The Network Reputation User Override service enables URL classification overrides. Any URL can be overridden to malicious, suspicious, or known. Overrides are visible to all users within the same organization. The service also supports listing existing overrides.

URL User Override Query​

This query sends network data to be overridden, and returns a list of network locations that were successfully overridden along with a list of invalid network locations and a list of network locations for which the override was successfully removed. All the parameters must be passed in the request body (either as JSON or XML).

Request​

POST /api/networking/user_override/v1/query/{post_format}
  • post_format
    • allows choosing between XML and JSON format in the POST payload

Request body:

{
  "rl": {
    "query": {
      "user_override": {
        "override_network_locations": [
          {
            "network_location": "string",
            "type": "string",
            "TTL": "string",
            "classification": "string",
            "threat_level": "string",
            "categories": [
              "string"
            ]
          }
        ],
        "remove_overrides": [
          {
            "network_location": "string",
            "type": "string"
          }
        ]
      },
      "response_format": "string"
    }
  }
}
  • override_network_locations
    • List of network locations that the user wants to override
    • Optional
  • network_location
    • Network location that the user wants to override.
    • Required
  • type
    • Type of URI that was listed in the network_location parameter. Supported types: url.
    • Required
  • TTL
    • Specifies the duration (in seconds) for which an override is valid. It defines the lifespan of the override before it expires and needs to be reassessed or renewed. In case the TTL is not set, there will be no expiration.
    • Optional
  • classification
    • Classification assigned to the URI in network_location. Allowed types correspond to the ReversingLabs classification scheme: malicious, suspicious, known, unknown.
    • Required
  • threat_level
    • Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is 0. If the value is not set, the default value is 0. For suspicious and malicious URIs, the allowed values are 1, 2, 3, 4, or 5. If the value is not set, the default value is 5. For unknown URIs, setting the value is not allowed, and the value will default to None.
    • Optional
  • categories
    • List of categories that the URI in question belongs to. List items are strings. The strings are arbitrary values.
    • Optional
  • remove_overrides
    • List of network locations that the user wants to remove overrides from. Items in this list are objects. An object must contain two fields: network_location and type. These fields take in the same types of values as their equivalents in the override_network_locations parameter.
    • Optional
  • response_format
    • Allows choosing between XML and JSON format for the response. Default is xml.
    • Optional

The request body of the query must contain the override_network_locations field or the remove_overrides field or both.

Response​

{
  "rl": {
    "user_override": {
      "created_overrides": [],
      "removed_overrides": []
    }
  }
}

rl.user_override.created_overrides[] and rl.user_override.removed_overrides[]

{
  "network_location": "string",
  "type": "string",
  "ttl": 0,
  "classification": "string",
  "categories": [
    "string"
  ],
  "reason": "string",
  "threat_level": 0
}
  • created_overrides
    • List of network locations for which overrides were created.
  • network_location
    • The overridden URI.
  • type
    • Type of URI that was listed in the network_location parameter.
  • TTL
    • Duration (in seconds) specified by the user for which an override is valid. It defines the lifespan of the override before it expires and needs to be reassessed or renewed. In case the TTL is not set, there will be no expiration.
  • classification
    • Classification that the user listed in the request.
  • threat_level
    • Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is 0. If the value is not set, the default value is 0. For suspicious and malicious URIs, the allowed values are 1, 2, 3, 4, or 5. If the value is not set, the default value is 5. For unknown URIs, setting the value is not allowed, and the value will default to None.
  • categories
    • List of categories that the requested URI belongs to.
  • removed_overrides
    • List of network locations from which overrides were removed, along with their type.
  • invalid_network_locations
    • List of invalid network locations.

List User URL Overrides Query​

This query returns the list of overrides that the user has made.

Request​

GET /api/networking/user_override/v1/query/list_overrides?[format=xml|json]&next_network_location={next page SHA1}

Query parameters:

  • next_network_location: SHA1 hash of the next network location in the response. In case the response has reached the maximum number of entries for a single response (1000), paging is used.
  • format: response format (JSON/XML)

Response format​

{
  "rl": {
    "user_override": {
      "next_network_location": "string",
      "network_locations": []
    }
  }
}

rl.user_override.network_locations[]

{
  "network_location": "string",
  "type": "string",
  "classification": "string"
}
  • network_location
    • Network location (URI) that is overridden.
  • type
    • Type of network location. Currently, only URLs are supported.
  • classification
    • Classification assigned to the URI in network_location. Allowed types correspond to the ReversingLabs classification scheme: malicious, suspicious, known, unknown.
  • expiration_time
    • The specific time and date when the override will expire, calculated based on the TTL value provided. If the TTL is not set, the expiration_time will indicate no expiration.
  • threat_level
    • Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is 0. If the value is not set, the default value is 0. For suspicious and malicious URIs, the allowed values are 1, 2, 3, 4, or 5. If the value is not set, the default value is 5. For unknown URIs, setting the value is not allowed, and the value will default to None.

Examples​

Example 1​

This request assigns an override to two network locations, and removes an existing override from a third network location. One of the new overrides is invalid.

Request:

/api/networking/user_override/v1/query/json

{
  "rl": {
    "query": {
      "user_override": {
        "override_network_locations": [
          {
            "network_location": "https://location-example.com",
            "type": "url",
            "classification": "malicious",
            "categories": [
              "phishing"
            ]
          },
          {
            "network_location": "http://test.com",
            "type": "url",
            "classification": "suspicious"
          }
        ],
        "remove_overrides": [
          {
            "network_location": "https://example.com",
            "type": "url"
          }
        ]
      },
      "response_format": "json"
    }
  }
}

Response:

{
  "rl": {
    "user_override": {
      "created_overrides": [
        {
          "network_location": "https://location-example.com",
          "type": "url",
          "classification": "malicious",
          "categories": [
            "phishing"
          ]
        }
      ],
      "removed_overrides": [
        {
          "network_location": "https://example.com",
          "type": "url"
        }
      ],
      "invalid_network_locations": [
        "http://test.com"
      ]
    }
  }
}

Example 2​

This request returns a list of overrides by the user.

Request:

/api/networking/user_override/v1/query/list_overrides?format=json

Response:

{
  "rl": {
    "user_override": {
      "network_locations": [
        {
          "network_location": "https://location-example.com",
          "type": "url",
          "classification": "malicious"
        }
      ],
      "next_network_location": "9865c7ecda437034e1513cc43ae9a1f6f334bb7f"
    }
  }
}

Example 3​

This request returns a list of overrides by the user, in paginated form.

Request:

/api/networking/user_override/v1/query/list_overrides?next_network_location=9865c7ecda437034e1513cc43ae9a1f6f334bb7f&format=json

Response:

{
  "rl": {
    "user_override": {
      "network_locations": [
        {
          "network_location": "https://location-example.com",
          "type": "url",
          "classification": "malicious"
        }
      ],
      "next_network_location": null
    }
  }
}

Custom Response Status Codes​

This API implements custom response status codes:

CODEDESCRIPTION
413The request contained more than the maximum allowed amount of network locations (100).