FauxAPI, a REST based API for pfSense

[ndj]

Published and announced under the Development topic last week a pfSense 2.3+ package last implements an API interface for pfSense.  Not a whole lot of traffic or feedback over there so posting under the Packages topic herewith.

FauxAPI enables easier dev-ops with pfSense by enabling easy programatic change to pfSense.

You can easily download and install the package, read here:-
https://github.com/ndejong/pfsense_fauxapi/tree/master/package

Documentation here:-
https://github.com/ndejong/pfsense_fauxapi/blob/master/README.md

Project:-
https://github.com/ndejong/pfsense_fauxapi

Enjoy and send feedback,
N

[hvisage]

Hi there,

This looks interesting, just a quick q: is it a all or nothing type config load? ie. I can't upload just a subset of the config to be merged into or issue a "delete" of some part of the config, can I?

Will look more in depth when I need to, but at present that is what I saw from a first cursory glance over the API/README.md

[ndj]

Correct - because the layout and structure of the pfSense config XML looks like it can change between versions I did not want to have to maintain a knowledge of the XMLTree variations between those versions.

The provided Python library can perform section by section configuration changes, however if you take a look under the covers you'll notice it achieves this by doing a full config pull, followed by a replace and a full config push again.

[ndj]

FauxAPI has received an update to v1.1

In brief:-

• new API call alias_update_urltables - forces the immediate update of remote URL tables
• new API call gateway_status - returns the current status of the gateways
• updated documentation
• tested against pfSense 2.3.2 and 2.3.3

The package has received some great feedback and users deploying in complex large environments - enjoy, send feedback.

Pardon the cross post across from the Development forum.

N

[ndj]

FauxAPI latest release is now v1.2 which introduces the (experimental) capability to perform full remote pfSense function calls.

API Action Summary:-

• alias_update_urltables - Causes the pfSense host to immediately update any urltable alias entries from their (remote) source URLs.

• config_backup - Causes the system to take a configuration backup and add it to the regular set of system change backups.

• config_backup_list - Returns a list of the currently available system configuration backups.

• config_get - Returns the system configuration as a JSON formatted string.

• config_reload - Causes the pfSense system to perform a reload of the config.xml file.

• config_restore - Restores the pfSense system to the named backup configuration.

• config_set - Sets a full system configuration and (by default) reloads once successfully written and tested.

• function_call - Call directly a pfSense PHP function with API user supplied parameters.

• gateway_status - Returns gateway status data.

• rule_get - Returns the numbered list of loaded pf rules from a pfctl -sr -vv command on the pfSense host.

• send_event - Performs a pfSense "send_event" command to cause various pfSense system actions.

• system_reboot - Reboots the pfSense system.

• system_stats - Returns various useful system stats.

https://github.com/ndejong/pfsense_fauxapi

[garethrobson]

I would absolutely love to start using this…but after an hour of trying, I cannot get the authentication to work! Im using powershell to communicate so the methods are different but I think its my understanding of the authentication that appears to be the issue.

The following response is received by powershell:
"callid":"5aafcdce2c7cf","message":"authentication failed"}

----REMOVED----

----REMOVED----

Can you see if I am doing anything wrong here? If this all seems correct then I will do further digging into the powershell.

Thanks!

[ndj]

Have you taken a look at the debug logging output by adding the _debug parameter (see docs) ?

Pretty sure you’ll find the issue is with the SHA256 value expressed in uppercase, try using lowercase characters - if you still have issues post the debut output

[garethrobson]

Thanks for the reply.

Iv tried changing the hash output to lowercase but that hasnt worked.

I have tried adding all of the below to the URL but the output does not change or give me more info (maybe because its not authenticated?):

&debug=true
&_debug=true
&__debug=true

any other ideas?

[garethrobson]

actually I think I have it working. I changed my random length from 5 to 8 and this seems to have done the trick. might be worth adding this requirement to the documentation :)

[ndj]

Generally &__debug=true is your friend and provides helpful debugging log information - if you are having trouble check this first, the log messaging will (or should) provide clear pointers to any FauxAPI issues.

You are correct about the nonce length, reading the code it needs to be >= 8 chars and <= 40 chars - however you should have received an error response with message somewhere in the JSON response:-

“length of nonce value is out-of-bounds”

If you have an interface in PowerShell that you’d be willing to contribute I’d be happy to accept the pull-request

N

[garethrobson]

Thanks for your help. I cant explain why the __debug=true wasnt displaying any more output other than that which I posted.

Everything is working now.

In terms of a powershell interface im afraid all that I have done is to replace the CURL and the hash command and parameters with the powershell alternatives. Im happy to send these over to you but im afraid iv never used github so I dont even know what a "pull" is let alone how to do one! haha!

[gremblin]

Thanks ndj for this application. I just got it working with Home Assistant for stat monitoring. Your authentication method made getting it hooked up a little bit of a challenge, but I do like that it makes it much more difficult to hack in.

I posted a how to on the HA Community Forums: https://community.home-assistant.io/t/pfsense-stat-monitor/61070

[ndj]

Hi @garethrobson - that's awesome, I added a link to your post here - https://nicholasdejong.com/fauxapi-for-pfsense/

[Savsia]

Hi, I recently installed the FauxAPI module, but in the Package Manager it appears in the status "Package is configured but not installed (fully) installed or deprecated", comemai? I followed all the instructions.

[ndj]

Hi @saveriozagaria - thanks for reporting.

I believe you are describing the fact that FauxAPI is not yet part of the pfSense plugins and as such it gets flagged with a ! mark which when you hover across it gives a message "Package is installed, but is not available on remote repository"

This is warning message unlikely to change until the pfSense (Netgate) team are able to find time to review and accept the fauxapi into their repo - I resubmitted a Pull Request back in July 2018:-

• https://github.com/pfsense/FreeBSD-ports/pull/531

---

Because I am here, a few things to mention:-

• there was also a new point release (1.3.2) last week to address an issue with non-standard ports
• the package passes all tests etc and has been tested up to 2.4.3-RELEASE-p1
• some nice new Python example code managing user and groups available
• https://github.com/ndejong/pfsense_fauxapi/tree/master/extras/examples

[jullienl]

@garethrobson I have been trying to make PowerShell work with the FauxAPI but without success so far, I always get a 401 authentication failure. Would you mind sharing your code? I suspect the way I create my fauxapi-auth is wrong, thanks

[jullienl]

@garethrobson I finally got it work using the following code:

$pfsense = "192.168.1.1"


# Creation of the header

$headers = @{} 

    $TimeNow = (Get-Date).ToUniversalTime()
    $timestamp = Get-Date $TimeNow -UFormat "%Y%m%dZ%H%M%S" 
    $apikey = "PFFAxxxxxxxxxxxx"
    $apisecret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    $nonce = (Get-Date).Ticks
    
    $string = $apisecret + $timestamp +  $nonce


    Function Get-StringHash([String] $String,$HashName = "MD5") 
    { 
        $StringBuilder = New-Object System.Text.StringBuilder 
        [System.Security.Cryptography.HashAlgorithm]::Create($HashName).ComputeHash([System.Text.Encoding]::UTF8.GetBytes($String))|%{ 
        [Void]$StringBuilder.Append($_.ToString("x2")) 
        } 
        $StringBuilder.ToString() 
    }

    
$hash = Get-StringHash $string "SHA256"
 
$fauxapiauth = $apikey + ":" + $timestamp + ":" + $nonce + ":" + $hash

$headers["fauxapi-auth"] = $fauxapiauth

# Added these lines to avoid the error: "The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel."
# due to an invalid Remote Certificate
    add-type -TypeDefinition  @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;
        public class TrustAllCertsPolicy : ICertificatePolicy {
            public bool CheckValidationResult(
                ServicePoint srvPoint, X509Certificate certificate,
                WebRequest request, int certificateProblem) {
                return true;
            }
        }
"@
    [System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12    
    

$response = Invoke-WebRequest -Uri "https://$pfsense/fauxapi/v1/?action=config_backup_list" -Headers $headers -Method GET   
   
$request = ($response.content | Convertfrom-Json).data.backup_files

[ndj]

Hi @jullienl - could you add a __debug=true as a URL parameter and provide the response message in this thread - authentication failures have plenty of logging and messages around them to help identify where problem(s) might be coming from - should be fairly easy to resolve - N