api.md

WiFi Pineapple Module API

Introduction

Unlike the old web interface, the back end of the new interface has been decoupled from the front end. All requests to perform system actions are sent as POSTs to /api/. The content of the POST is JSON and contains a minimum of two parameters.

The first parameter key must be either system or module

system is used for core system functions such as logging users in and performing system setup as well as managing notifications. module is used when sending a request to any of the default modules or to any user modules. The value is set to the module with which you are trying to communicate. For example, "system": "notifications" or "module": "RandomRoll".

The second parameter key action

This is set to the action you wish to perform. For instance, this could be "action": "listNotifications" or "action": "getRandomRollRolls".

Any other parameters are optional and are specific to the module and action you are requesting

Many actions do not require additional parameters. For instance, {"system": "notifications", "action": "listNotifications"} will return a list of all of the current unread notifications (as JSON). However, there are some functions, such as addNotification, that require additional parameters (in this case message). To create a new notifications, one would use the following request:

{
  "system": "notifications",
  "action": "addNotification",
  "message": "Hello World!"
}

Authentication

(Please note that extra authentication parameters are not required when using the angular module api due to the fact that client side module components are loaded after the user authenticates their browser)

There are a couple ways to authenticate with the pineapple. Requests sent via the web interface use a PHPSESSID cookie as well as an X-XSRF-TOKEN header. The pineapple will verify that the session is valid and logged in and that the XSRF token matches the one generated at the start of the session. If both of these conditions are met, the request is routed. An example of a request sent by chrome is as follows:

POST /api/ HTTP/1.1
Host: 172.16.42.1:1471
Connection: keep-alive
Content-Length: 55
Accept: application/json, text/plain, */*
Origin: http://172.16.42.1:1471
X-XSRF-TOKEN: b01c5046faa2f8ffbed6f2fdd90a5605e6c505e3
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36
Content-Type: application/json;charset=UTF-8
Referer: http://172.16.42.1:1471/
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Cookie: PHPSESSID=cfd6b0bb983666362cae311c457d1d34; XSRF-TOKEN=b01c5046faa2f8ffbed6f2fdd90a5605e6c505e3

{"system":"notifications","action":"listNotifications"}

This type of authentication is awkward and clumbsy to implement programmatically. Because of this, we have added a new way to authenticate with the WiFi Pineapple: API tokens. Though API tokens are supported by default, the pineapple is shipped without any valid tokens. The process of generating API tokens is simplified by the API Tokens module. After a token has been generated, it can be sent as an additional parameter. To use an API token, simply add an additional apiToken key to the request body. For example, to add a notification, one could send the following JSON request:

{
  "system": "notifications",
  "action": "addNotification",
  "message": "Hello World!",
  "apiToken": "7365626b696e6e652063616e7420636f6465202724ef6b5d7ac0b800cc83d474e8e007"
}

If the apiToken parameter is valid, the request will be route; otherwise an error will be returned.

Modules

Advanced

Description

The advanced module simplifies some more advanced processes like performing system upgrades and clearing system caches. For example, the following will clear the pineapple's caches:

{
  "module": "Advanced",
  "action": "dropCaches"
}

Action	Description	Parameters
getResources	Returns a JSON array of disk and memory usage	none
dropCaches	Clears system caches	none
getUSB	Returns a list of USB devices connected ot the pineapple	none
getFstab	Returns the contents of /etc/config/fstab	none
getCSS	Returns the contents of main.css	none
saveFstab	Overwrites /etc/config/fstab with a string	fstab A string to be written to /etc/config/fstab
saveCSS	Overwrites the contents of main.css with a string	css A string to be written to /pineapple/css/main.css
checkForUpgrade	Fetches the list of upgrades and the description of each	none
downloadUpgrade	Upgrades the pineapple to a specified firmare version (see output of checkForUpgrades and getCurrentVersion)	version The version to which the pineapple should be upgraded
getDownloadStatus	Tells whether a firmware download is complete or in progress and how many bytes have been downloaded	none
performUpgrade	Upgrades using the image in /tmp/upgrade.bin	none
getCurrentVersion	Returns the current firmware version on the pineapple	none

Clients

Description

The Clients module allows for the monitoring and management of connected clients. For example, the following would kick the client with the MAC address aa:bb:cc:dd:ee:ff:

{
  "module": "Clients",
  "action": "kickClient",
  "mac": "aa:bb:cc:dd:ee:ff"
}

Action	Description	Parameters
getClientData	Returns a JSON array of connected clients	none
kickClient	Kicks (disconnects) a connected client from the pineapple	mac The MAC address of the client to be kicked

Configuration

Description

The configuration module allows for the modification of several pineapple configuration options such as timezone and landing page. The example below would set the landing page content to <b><i>Pineapples are yummy</i></b>:

{
  "module": "Configuration",
  "action": "saveLandingPage",
  "landingPageData": "<b><i>Pineapples are yummy</i></b>"
}

Action	Description	Parameters
getCurrentTimeZone	Retrieves the current timezone of the pineapple	none
changeTimeZone	Changes the pineapple's timezone	timeZone The timezone to switch to
getLandingPageData	Gets the current landing page data	none
saveLandingPage	Changes the landing page content	landingPageData The text to which the landing page will be set
changePassword	Changes the password for the root user	newPassword The new password for the root user newPasswordRepeat For verification, must be the same as newPassword oldPassword The current password for root
resetPineapple	Resets the pineapple (executes mtd erase rootfs_data)	none
haltPineapple	Halts the pineapple	none
rebootPineapple	Reboots the pineapple	none
getLandingPageStatus	Shows whether the landing page is enabled or not	none
enableLandingPage	Enables the landing page	none
disableLandingPage	Disables the landing page	none

Dashboard

Description

You can use the Dashboards API to return useful values such as CPU usage, total SSIDs, SSIDs discovered this session and uptime. For example, the following will get the bulletins:

{
  "module": "Dashboard",
  "action": "getBulletins"
}

Action	Description	Parameters
getOverviewData	Return an array containing cpu, uptime, clients, SSIDs and newSSIDs.	none
getLandingPageData	Return all landing page browser stats	none
getBulletins	Return bulletins	none

Filters

Description

The filters module has API that will allow you manage all aspects of the Filter module externally, such as getting client data or adding clients. It is used like so:

{
    "module": "Filters",
    "action": "getClientData"
}

Action	Description	Parameters
getClientData	Return an array of client filters. (Mode and Filters)	none
getSSIDData	Return an array of SSID filters (Mode and Filters)	none
toggleClientMode	Toggle between whitelist and blacklist mode for client filtering	none
toggleSSIDMode	Toggle between whitelist and blacklist mode for SSID filtering	none
addClient	Add client to filter	mac MAC address of client
addSSID	Add SSID to filter	ssid SSID of Access Point
removeClient	Remove client from filter	mac MAC address of client
removeSSID	Remove SSID from filter	ssid SSID of Access Point

Logging

Description

The Logging module provides easy access to the syslog, dmesg, PineAP and Reporting logs. To use these API functions, send your api request with the "module" set to "Logging":

{
    "module": "Logging",
    "action": "getSyslog",
}

Action	Description	Parameters
getSyslog	Return the system log in full	none
getDmesg	Return the kernel log in full	none
getReportingLog	Return the log from the Reporting module	none
getPineapLog	Return the log from PineAP	none
clearPineapLog	Clear the PineAP log file	none
getPineapLogLocation	Return the location of the PineAP log	none
setPineapLogLocation	Set the location for PineAP logging	location New location of PineAP log.

ModuleManager

Description

The Module Manager is responsible for installing, removing, and upgrading modules. It's API can be used to manage modules, as well as fetching the list of installed modules and getting available modules. To use them in your module, your request body would look like this:

{
    "module": "ModuleManager",
    "action": "removeModule",
    "moduleName": "Module"
}

Action	Description	Parameters
getAvailableModules	Return an array of modules available for download	none
getInstalledModules	Return an array of modules currently installed	none
downloadModule	Download a specified module	moduleName Name of module to install destination Destination of module.(sdcard or internal)
installModule	Install a specified module	moduleName Name of module to install destination Destination of module.(sdcard or internal)
removeModule	Remove a specified module	moduleName Name of module to remove
downloadStatus	Check status of module download	none
installStatus	Check status of module install	none
checkDestination	Check if the specified destination has the specified space free	name Name of module size Size of module

Networking

Description

The Networking module API allows you to interface with the networking side of the WiFi Pineapple without having to write your own functions to manage interfaces, the DNS, and the routing table. As described above, you can use these actions in your own module like so:

{
    "module": "Networking",
    "action": "setHostname",
    "hostname": "Pineapple"
}

Action	Description	Parameters
getRoutingTable	Returns the routing table of the Pineapple	none
restartDNS	Restarts the DNS service on the Pineapple	none
updateRoute	Updates the routing table	routeIP IP Address for the route routeInterface Interface for the route
getAdvancedData	Returns the hostname and ifconfig	none
setHostname	Sets the hostname for the Pineapple	hostname String for the hostname
resetWirelessConfig	Resets the Wireless Configuration for the Pineapple	none
getInterfaceList	Returns an array of available network interfaces	none
saveAPConfig	Writes properties to the AP configuration	selectedChannel Channel for the AP to operate on openSSID String for the SSID of the Open Access Point hideOpenAP Boolean to hide the Open Access Point or not managementSSID String for the SSID of the Management AP managementKey string for the WPA2 passphrase for the Management AP disableManagementAP Boolean to disable the Management AP or not
getAPConfig	Returns an array of properties from the access point configuration.	none
getMacData	Returns the MAC Addresses of each of the wireless interfaces	none
setMac	Sets the MAC address for a specified interface	random Boolean to set the MAC address as a random value. interface The interface you want to change the MAC address of mac The new MAC address of the interface
resetMac	Reset the specified interface's MAC address to the factory default.	interface The interface to reset

PineAP

Description

The PineAP module provides an easy way to interface with the PineAP suite. For example, one might use the following to add an SSID to PineAP's pool:

{
  "module": "PineAP",
  "action": "addSSID",
  "ssid": "ACME WiFi"
}

Action	Description	Parameters
getPool	Returns an array of the SSIDs in PineAP's pool	none
clearPool	Clears the PineAP pool	none
addSSID	Adds an SSID to the pool	ssid The SSID string to add
removeSSID	Removes an SSID from the pool	ssid The SSID string to remove
setPineAPSettings	Update PineAP's settings	settings A dictionary with setting key/value pairs allowAssociations Whether clients should be allowed to associate to the pineapple logProbes Whether to log probe requests logAssociations Whether to log associations beaconResponses Whether to send beacon responses captureSSIDs Whether to add sniffed SSIDs to the pool broadcastSSIDs Whether to broadcast the SSID pool beaconInterval The beacon interval- must be one of "low", "normal" or "aggressive" responseInterval The response interval- must be one of "low", "normal" or "aggressive" targetMAC The MAC to target with responses sourceMAC The MAC PineAP should spoof
getPineAPSettings	Returns a dictionary with all the current PineAP settings	none
deauth	Deauth a list of clients from a station. Use this with caution. The misuse of this function may be illegal in some places.*	sta The bssid of the station from which to disconnect the clients clients An array of client MACs to deauth multiplier The number of deauths (from 1 to 10) to send channel The channel to hop to before sending the frame(s)
enable	Enables PineAP	none
disable	Disables PineAP	none
saveAsDefault	Makes the current configuration persist after reboots	none
downloadPineAPPool	Get a download link to the SSID pool (useful for client side modules)	none

Recon

Description

The recon module allows for the detection of access points and clients within range of the pineapple. The following example would scan for nearby access points:

{
  "module": "Recon",
  "action": "startScan",
  "scanType": "apOnly"
}

Action	Description	Parameters
startScan	Starts a new scan	scanType The type of scan to perform (either apOnly or clientAp) scanDuration The duration to of time (in seconds) to scan for
scanStatus	Get the status or results of a scan	scan A JSON encoded scan object (e.g.{"scanID": "1234567895", "scanType": "apOnly"})

Reporting

Description

The reporting module allows you to control the automatic reporting features of the pineapple. For example, the following would return report contents:

{
  "module": "Reporting",
  "action": "getReportContents"
}

Action	Description	Parameters
getReportConfiguration	Gets the current reporting configuration	none
getReportContents	Gets the report contents	none
getEmailConfiguration	Gets the current email configuration for reporting	none
setReportConfiguration	Changes the report configuration	config A JSON object containing the new configuration (eg. {"storeReport": true, "sendReport": true, "interval": 1, "generateReport": true})
setReportContents	Set which items get reported	config A JSON object containing the new configuration (eg. {"pineAPLog": true, "clearLog": true, "siteSurvey": false, "siteSurveyDuration": 0, "client": false, "tracking": false})
setEmailConfiguration	Set the email configuration

Tracking

Description

Tracking allows you to create custom scripts for tracking clients. The following example would set a new tracking script:

{
  "module": "Tracking",
  "action": "saveScript",
  "trackingScript": "#!/bin/bash\n\nMAC=$1\nTYPE=$2 # 0 PROBE; 1 ASSOCIATION\nSSID=$3\n"
}

Action	Description	Parameters
getScript	Gets the current tracking script contents	none
saveScript	Sets the current tracking script contents	trackingScript The tracking script contents
getTrackingList	Gets the current list of clients being tracked	none
addMac	Adds a MAC to tracking	mac The MAC address to start tracking
removeMac	Removes a MAC from tracking	mac The MAC address to stop tracking

Module.php API

Every module must extend the Module class that resides in Module.php. Extending this class gives the module access to the following API functions. For more information, see Creating Modules.

Function	Arguments	Description	Usage
execBackground()	command	Will execute command in the background.	`$this->execBackground("ifconfig wlan1 down");
installDependency()	dependencyName	Will use opkg to install dependencyName.	$this->installDependecy('nmap');
checkDependency()	dependencyName	Will use opkg to check is dependencyName is installed.	$this->checkDependency('nmap');
checkRunning()	processName	Will check to see if processName is currently running on the system.	$this->checkRunning('nmap');
uciGet()	uciString	Will use UCI to get value of supplied uciString	$this->uciGet("network.wan");
uciSet()	settingString value	Will use UCI to set the supplied value of supplied settingString.	$this->uciSet("network.wan.ifname", "wan2");
uciAddList()	settingString value	Will use UCI to create a new list with supplied settingString and value.	$this->uciAddList("network", "wan3");

Community Python API

A community python API wrapper exists here but documentation is still in progress.

Further Information

made with <3