Skip to content

API (Work in progress!)

This document describes the API for the FOD Go version

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: the unix time when the rule expires
    • applier: the user that last changed the rule
    • status: the status of the firewall rule, "active", "inactive", "pending" or "unknown"
    • change_time: the unix time the rule was last changed

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": 1964851877,
    "applier": "admin2",
    "status": "inactive",
    "change_time": 1764944720
  }
]

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: the unix time when the rule expires
  • 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 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": 1964851877,
    "status": "inactive",
    "change_time": 1764944720
}

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: the unix time when the rule expires
  • applier: the user that last changed the rule
  • status: the status of the firewall rule, "active", "inactive", "pending" or "unknown"
  • change_time: the unix time the rule was last changed

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": 1964851877,
    "applier": "admin2",
    "status": "inactive",
    "change_time": 1764944720
}

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:

[
  {
    "timestamp": 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: the unix time when the rule expires
  • status: the status of the rule, "inactive" or "active"
  • Response Body: None

This request updates a rule only with the fields that are given in the request body

To send this request with curl:

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

where data can e.g. be

'{"status":"inactive"}'

which would deactivate a rule