Skip to content

API

This document describes the API for FoD

Error responses

When an error is returned, the server returns the following JSON:

{
    "error": "error message",
    "error_details": ...,
}

error_details is optional here.

Authentication

To authenticate with the API a token is needed. To generate a token, go to the FOD deployment in the web browser and go to Profile. At the Profile page you will see a button to create an API key. Save this API key securely.

To then authenticate with the API, the token has to be given as a bearer token using the Authorization header. Example with curl:

$ curl -H "Authorization: Bearer yourtokenhere

Getting profile information

  • Method: GET
  • Path: /api/v1/profile
  • Request Body: None
  • Response Body:
  • user_name: The name of the user
  • networks: Networks the user has access to, list of:
    • id: The uuid of the network
    • name: The name of the network
    • cidrs: The subnets of the network
  • is_super: Whether this user is a super user (administrator)

The first request you will likely send in your request is getting profile information. An example response is the following:

{
  "user_name": "admin",
  "networks": [
    {
      "id": "019aeedd-59e7-7655-acf9-c95074b84d03",
      "name": "fod",
      "cidrs": [
        "127.0.0.1/32"
      ]
    }
  ],
  "is_super": true
}

To send this request with curl:

$ curl -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/profile

Getting all rules for a network

  • Method: GET
  • Path: /api/v1/networks/{uuid}/rules
  • Request Body: None
  • Response Body: List of:
    • id: the uuid of the rule
    • name: the name of the rule
    • description: the description
    • source: the source IP CIDR
    • source_ports: the port range list for the source. List of:
    • begin: the begin port range, including
    • end: the end port range, including
    • destination: the destination IP CIDR
    • destination_ports: the port range list for the destination. List of:
    • begin: the begin port range, including
    • end: the end port range, including
    • ports: the port range for common ports. List of:
    • begin: the begin port range, including
    • end: the end port range, including
    • protocols: the list of protocol strings
    • fragment: the list of fragment types
    • action: the action, "discard" or "rate-limit"
    • rate_limit (omitted if action is not rate-limit): the number of bytes to rate limit
    • expires_at: the unix time when the rule expires. Negative meaning it does not expire
    • applier: the user that last changed the rule
    • status: the status of the firewall rule, "active", "inactive", "activating", "deactivating" or "unknown"
    • last_modified_at: the unix time the rule was last modified
    • flowspec_modes: the FlowSpec Modes

To get all network rules for a network, you need the network uuid from the network you have access to. This can be found in the /profile response.

Using this UUID, you can send a GET request to get the rules. Example response:

[
  {
    "id": "019aeee0-31dc-73e8-abc2-ba05d432221b",
    "name": "test",
    "description": "",
    "source": "0.0.0.0/0",
    "destination": "127.0.0.1/32",
    "source_ports": [],
    "destination_ports": [],
    "ports": [],
    "protocols": [
      "TCP"
    ],
    "fragments": null,
    "action": "rate-limit",
    "rate_limit": 0,
    "expires_at": 1964851877,
    "last_modified_by_uid": "admin2",
    "status": "inactive",
    "last_modified_at": 1764944720,
    "flowspec_modes": ["global"]
  }
]

To send this request with curl:

$ curl -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/networks/uuidhere/rules

Creating a network rule

  • Method: POST
  • Path: /api/v1/networks/{uuid}/rules
  • Request Body:
  • name: the name of the rule
  • description: the description
  • source: the source IP CIDR
  • source_ports: the port range list for the source. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • destination: the destination IP CIDR
  • destination_ports: the port range list for the destination. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • ports: the port range for common ports. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • protocols: the list of protocol strings
  • fragment: the list of fragment types
  • action: the action, "discard" or "rate-limit"
  • rate_limit (omitted if action is not rate-limit): the number of bytes to rate limit
  • expires_at: the unix time when the rule expires. Negative meaning it does not expire
  • flowspec_modes: the FlowSpec Modes, optional. If not given it uses the default
  • Response Body:
  • rule_id: the uuid of the rule that was created

Like the GET request to get all the rules, the POST request also needs the network UUID. Example response

{
    "rule_id": "019aeee0-31dc-73e8-abc2-ba05d432221b"
}

This is the uuid of the rule that has been created

To send this request with curl:

$ curl -d @rule.json -X POST -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/networks/uuidhere/rules

where rule.json is a file with the following information

{
    "name": "test",
    "description": "",
    "source": "0.0.0.0/0",
    "destination": "127.0.0.1/32",
    "source_ports": [],
    "destination_ports": [],
    "ports": [],
    "protocols": [
      "TCP"
    ],
    "fragments": null,
    "action": "rate-limit",
    "rate_limit": 0,
    "expires_at": 1964851877,
    "status": "inactive",
    "flowspec_modes": ["global"]
}

Getting rule information

  • Method: GET
  • Path: /api/v1/rules/{uuid}
  • Request Body: None
  • Response Body:
  • id: the uuid of the rule
  • name: the name of the rule
  • description: the description
  • source: the source IP CIDR
  • source_ports: the port range list for the source. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • destination: the destination IP CIDR
  • destination_ports: the port range list for the destination. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • ports: the port range for common ports. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • protocols: the list of protocol strings
  • fragment: the list of fragment types
  • action: the action, "discard" or "rate-limit"
  • rate_limit (omitted if action is not rate-limit): the number of bytes to rate limit
  • expires_at: the unix time when the rule expires. Negative meaning it does not expire
  • applier: the user that last changed the rule
  • status: the status of the firewall rule, "active", "inactive", "pending" or "unknown"
  • last_modified_at: the unix time the rule was last changed
  • flowspec_modes: the FlowSpec Modes

This is used to get information for a single rule. The UUID for the rule can be obtained when a rule was created or when listing all rules

Example response:

{
    "id": "019aeee0-31dc-73e8-abc2-ba05d432221b",
    "name": "test",
    "description": "",
    "source": "0.0.0.0/0",
    "destination": "127.0.0.1/32",
    "source_ports": [],
    "destination_ports": [],
    "ports": [],
    "protocols": [
      "TCP"
    ],
    "fragments": null,
    "action": "rate-limit",
    "rate_limit": 0,
    "expires_at": 1964851877,
    "last_modified_by_uid": "admin2",
    "status": "inactive",
    "last_modified_at": 1764944720,
    "flowspec_modes": ["global"]
}

To send this request with curl:

$ curl -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/rules/uuidhere

Getting rule statistics

  • Method: GET
  • Path: /api/v1/rules/{uuid}/statistics
  • Request Body: None
  • Response Body:
  • timestamp: the unix timestamp the statistic was recorded
  • bytes_matched (only present when the rule is rate limit): how many bytes were matched
  • bytes_dropped: how many bytes were dropped
  • packets_matched (only present when the rule is rate limit): how many packets were matched
  • packeys_dropped: how many packets were dropped

Rules also have a separate endpoint to get statistics: e.g. how many bytes are dropped by this rule. Example response:

[
  {
    "measured_at": 1764946210,
    "bytes_matched": 79,
    "bytes_dropped": 1,
    "packets_matched": 6,
    "packets_dropped": 4
  }
]

To send this request with curl:

$ curl -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/rules/uuidhere/statistics

Patching a rule

  • Method: PATCH
  • Path: /api/v1/rules/{uuid}
  • Request body: Each field optional:
  • name: the name of the rule
  • description: the description
  • source: the source IP CIDR
  • source_ports: the port range list for the source. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • destination: the destination IP CIDR
  • destination_ports: the port range list for the destination. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • ports: the port range for common ports. List of:
    • begin: the begin port range, including
    • end: the end port range, including
  • protocols: the list of protocol strings
  • fragment: the list of fragment types
  • action: the action, "discard" or "rate-limit"
  • rate_limit (omitted if action is not rate-limit): the number of bytes to rate limit
  • expires_at: the unix time when the rule expires. Negative meaning it does not expire
  • flowspec_modes: the FlowSpec Modes
  • Response Body: None

This request updates a rule only with the fields that are given in the request body. It activates the changed rule if the current rule is set to active. Otherwise, the rule is edited but the status is not changed.

To send this request with curl:

$ curl -X PATCH -d data -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/rules/uuidhere

where data can e.g. be

'{"name":"newname"}'

which would change the name to "newname"

Activating a rule

  • Method: POST
  • Path: /api/v1/rules/{uuid}/activate
  • Request Body: None
  • Response: HTTP 204 No content or HTTP 304 Not Modified if nothing changed

This activates a rule

To send this request with curl:

$ curl -X POST -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/rules/activate

Note that this validates if the rule also has e.g. correct expiry. This is essentially an edit of the rule in the UI but keeping all the fields the same.

Deactivating a rule

  • Method: POST
  • Path: /api/v1/rules/{uuid}/deactivate
  • Request Body: None
  • Response: HTTP 204 No content or HTTP 304 Not Modified if nothing changed

This deactivates a rule

To send this request with curl:

$ curl -X POST -H "Authorization: Bearer yourtokenhere" https://127.0.0.1/api/v1/rules/deactivate