FWCLOUD-API | FWCLOUD

API

One of the main modules that are part of FWCloud is its REST API. It provides the means to carry out all the actions allowed by FWCloud, such as managing firewalls, rules and IP objects, compiling/installing policies, managing VPNs, etc. Also, any action performed using the API will be reflected immediately in the user interface.

FWCloud-API is a really powerful tool, allowing us to become independent of the user interface (FWCloud-UI) to perform many tasks, such as:

Your own user interface

You can create a custom user interface, completely independent of FWCloud-UI.

Dynamic rules

You can create new rules using API calls to perform a variety of tasks, such as for blocking an IP address automatically.

Status

You can get status information, such as the active OpenVPN connections over a firewall.

Dynamic node management

You can use the API to add and remove nodes to a firewalls cluster dynamically. For example, think of a group of web fronts that grows and shrinks dynamically depending on the load, and whose security policy is managed using FWCloud. It’s possible to add or remove cluster nodes through FWCloud-API and install the latest security policy to the newly created node.

To develop the API we have used Node.js, a server side Javascript environment based on events that executes code asynchronously.

Among the multiple Node.js packages that we have used, it’s worth to mention Express, a framework that helps greatly developing a REST API like the one we’ve created for the FWCloud project. Moreover, it provides the right tools to make the application more secure and robust.

Among all the Express features, we can highlight the following:

It allows to create RESTful APIs easily.

Create route tables based on the method and URL of the HTTP request to run the code associated to an specific API call.

It allows to define middleware methods, this is, code that will run for all the HTTP requests sent to the API. This is really useful, because it eases complex tasks like user authentication, data validation, access control and so forth.

How to use FWCloud-API.

Once that we have FWCloud-API installed and running, as explained in the installation section, we can start communicating with it using the HTTP/HTTPS protocol, just like any other REST API.

To do that, the only thing we need to know is the available API calls and the parameters needed for each call.

A call to theFWCloud-API is formed by the following elements:

METHOD

HTTP method used (POST, GET, PUT, DELETE, etc.).

URL

(Uniform Resource Locator): Also known colloquially as web address. It’s a reference to a web resource that designates its location in a computer network, and also the communication protocol used to obtain that resource.

PARAMETERS

Parameter set needed by the FWCloud server to process the API call. To simplify, FWCloud-API only allows parameters in the request body, and they must have JSON format. This is very useful because it simplifies greatly data validation process and access control. On the other hand, it has the disadvantage that it’s not possible to use GET and DELETE methods in some API calls that require parameters, but this is not a big drawback, as we’ll see later.

To understand better how to interact with FWCloud-API, we’ll see some simple examples.

The first thing we need to know is the IP address or domain name and the port in which our FWCloud-API installation is listening, this is, the access URL to the API. By default, TCP port 3000 is used in all the IPs of the server. If we’re not using the default settings, the file .env of the root folder of the installation contains the following options that define this configuration.

LISTEN_IP=0.0.0.0 LISTEN_PORT=3000

Let’s suppose that our FWCloud-API server has the default configuration and that we’re accessing the API from the server itself. Also, we’re using HTTPS protocol. As explained in the installation section, it’s very important to always use HTTPS protocol when communicating with the API to guarantee the confidentiality of the data sent and received. Therefore, all the access URL to our FWCloud-API installation will start like this:

https://localhost:3000/

Besides this, we need to know a valid origin. The valid origins are defined inside the .env file, in the following environment variable:

CORS_WHITELIST="https://ui.fwcloud.net, http://ui.fwcloud.net"

As explained in the installation section, these valid origins will vary from one installation to another. They will normally reference to the URL used to access FWCloud-UI.

Lastly, we need a customer code, user name and password to start a session on the API. The default login data for a new FWCloud-API installation are:

Customer code: 1
User: fwcadmin
Password: fwcadmin

Now that we have all the needed information, let’s see our first API call, the login one. This is a mandatory step before we can use any other available calls in FWCloud-API. To login, we need to call the URL https://localhost:3000/user/login using POST method, a valid origin (Origin header) and the appropriate parameters in the request body as a JSON object.

Using curl command, this would be the call to login into the system:

curl -insecure -X POST \ https://localhost:3000/user/login \ -H 'Content-Type: application/json' \ -H 'Origin: https://ui.fwcloud.net' \ -d '{ "customer": 1, "username": "fwcadmin", "password": "fwcadmin" }'

The result of this call will be a response with HTTP code 200, indicating that everything went fine, and a JSON object like thie following one:

{ "user": 1, "role": 1 }

Also, it will set a session cookie that we’ll need to use in further API calls:

Set-Cookie:FWCloud.net-cookie=s%3AWVEKxBqVTa1txYz2FlxqXiCCj6PHluKT.Ofh7vD3WoJdkB7IvZwbryDV9mGSnuBEybXNWRTGEfBc; Path=/; Expires=Wed, 05 Jun 2019 16:17:42 GMT

Let’s see one more example, using the API call to create a new FWCloud.

curl --insecure -X POST \ https://localhost:3000/fwcloud \ -H 'Content-Type: application/json' \ -H 'Origin: https://ui.fwcloud.net' \ -H 'cookie: FWCloud.net-cookie=s%3AWVEKxBqVTa1txYz2FlxqXiCCj6PHluKT.Ofh7vD3WoJdkB7IvZwbryDV9mGSnuBEybXNWRTGEfBc' \ -b FWCloud.net-cookie=s%3AWVEKxBqVTa1txYz2FlxqXiCCj6PHluKT.Ofh7vD3WoJdkB7IvZwbryDV9mGSnuBEybXNWRTGEfBc \ -d '{ "name": "My First FWCloud", "image": "", "comment": "" }'

Because it’s an API call to update (or create) content, we’ll receive a response with a confirmation token. We need to repeat the API call and send that token in a header named X-FWC-Confirm-Token. This is a sample token:

{ "fwc_confirm_token": "WVEKxBqVTa1txYz2FlxqXiCCj6PHluKT_OnTImiV44SK5OirRuoCW" }

This is a measure to increase security, because a confirmation token is required for all the actions that involve a data change.

So, we need to repeat the API call, but adding the received confirmation token this time:

curl --insecure -X POST \ https://localhost:3000/fwcloud \ -H 'Content-Type: application/json' \ -H 'Origin: https://ui.fwcloud.net' \ -H 'X-FWC-Confirm-Token: WVEKxBqVTa1txYz2FlxqXiCCj6PHluKT_OnTImiV44SK5OirRuoCW' \ -H 'cookie: FWCloud.net-cookie=s%3AWVEKxBqVTa1txYz2FlxqXiCCj6PHluKT.Ofh7vD3WoJdkB7IvZwbryDV9mGSnuBEybXNWRTGEfBc' \ -b FWCloud.net-cookie=s%3AWVEKxBqVTa1txYz2FlxqXiCCj6PHluKT.Ofh7vD3WoJdkB7IvZwbryDV9mGSnuBEybXNWRTGEfBc \ -d '{ "name": "My First FWCloud", "image": "", "comment": "" }'

We’ll get a response with HTTP code 200, stating that the operation succeeded and a JSON object like the following, with the ID of the FWCloud we just created:

{ "insertId": 1 }

Available API calls

FWCloud is an application with a wide range of functionalities, which use the services provided by FWCloud-API. This is, any action performed by an user in the frontend (FWCloud-UI) will be carried out by sending one or more requests to the back-end (FWCloud-API).

This makes that there quite a few API calls to cover all of the features and functions. Moreover, each time that new functionalities are added, it’s usual that new API calls will be needed.

To organize all the API calls in a simple way, we’ve grouped them together depending on the resource type for which they are used, following the routing mechanism of the Express package:

app.use(‘/user’, user);
app.use(‘/customer’, customer);
app.use(‘/fwcloud’, fwcloud);
app.use(‘/cluster’, cluster);
app.use(‘/firewall’, firewall);
app.use(‘/policy/rule’, policy_rule);
app.use(‘/policy/compile’, policy_compile);
app.use(‘/policy/install’, policy_install);
app.use(‘/policy/ipobj’, policy_ipobj);
app.use(‘/policy/interface’, policy_interface);
app.use(‘/policy/group’, policy_group);
app.use(‘/policy/types’, policy_types);
app.use(‘/policy/positions’, policy_positions);
app.use(‘/policy/openvpn’, policy_openvpn);
app.use(‘/policy/prefix’, policy_prefix);
app.use(‘/interface’, interface);
app.use(‘/ipobj’, ipobj);
app.use(‘/ipobj/group’, ipobj_group);
app.use(‘/ipobj/types’, ipobj_types);
app.use(‘/ipobj/positions’, ipobj_positions);
app.use(‘/ipobj/mark’, ipobj_mark);
app.use(‘/tree’, tree);
app.use(‘/tree/folder’, tree_folder);
app.use(‘/tree/repair’, tree_repair);
app.use(‘/vpn/pki/ca’, vpn_pki_ca);
app.use(‘/vpn/pki/crt’, vpn_pki_crt);
app.use(‘/vpn/pki/prefix’, vpn_pki_prefix);
app.use(‘/vpn/openvpn’, vpn_openvpn);
app.use(‘/vpn/openvpn/prefix’, vpn_openvpn_prefix);

For instance, the API calls that start with /user are used to manage the users that will have access to the API. The ones starting with /customer will be used for managing customers, /fwcloud for managing FWClouds, /firewall for firewalls, /policy for security policies, /vpn for VPN connections and so forth. Also, the methods are used consistently: POST to create new resources (customers, users, firewalls, VPNs, etc); PUT to update them, etc.

The reference documentation for each API call is being generated using the APIDOC tool, which allows to build a documentation from the comments included inside the source code. If we use a browser and we open the file existing index.html inside the apidoc folder in the installation folder, we’ll have access to the latest version of the API reference manual.

We’re using Postman as the tool to try the API calls and for the software test automation. This tool allows to generate a detailed documentation of all the tailored tests, which is really helpful as additional documentation to understant how the API works. This documentation is publicly accessible in the following URL: https://documenter.getpostman.com/view/6531497/S1TYUvym.

Inside the postman folder in the installation root folder we can see the latest version of the tests collection used to verify the correct working of the API.

Undocumented API calls

Although our efforts, there are many FWCloud-API calls that are pending to be documented, and we keep on working hard to finish thistask. However, this shouldn’t be a big drawback, as it’s possible to find out how every call works by accessing the project source code.

For example, let’s suppose that we want to find out how the API call to create a new FWCloud works. The first thing we need to do is to identify the URL and the HTTP method that we’ll use.

In the root folder where FWCloud-API is installed, we’ll see a folder called routes that contain all the API calls. In our case, we want to know how to create a new FWCloud, so we’ll move to the folder routes/fwcloud.

Once there, the file fwcloud.js contains all the API calls to managed FWCloud resources. Moving down we can see the section router.post, that has a route for creating a new FWCloud, which is: https://localhost:3000/fwcloud

Lastly, we need to know the parameters needed to make the POST call. We have this information in a middleware used to filter and validate the input data, that uses the JOI package. In the file middleware/input_validation.js we can see that, for the route /fwcloud it will use a file in the folder middleware/joi_schemas, specifically fwcloud.js, which defines the needed parameters for each API call that manages FWClouds.

In conclusion, if we have any undocumented API call, we can use the procedure above to find out how to use it. Also, feel free to contact with us using our contact form or use the forum in the web to ask any doubt that you could have using or installing FWCloud.