API

Here are the different routes provided by the application. You can implement whatever front-end you like on top of it.

The API supports HTTP Basic authentication through the Authorization Header. By default, each authorization is only valid for one request (ie. the sessions are automatically revoked after each request complete). You can ask for reusable sessions though. Here are the HTTP headers supported:

  • X-Reuse-Session: set it to true to be able to reuse sessions
  • X-Language: set it to whatever supported language you want

Don’t forget to call /logout once you’re done if you choose to use reusable sessions.

GET /api/admin/auth/backends

Returns a list of backends

GET method provided by the webservice.

Returns:Backends
PUT /api/admin/auth/users/(name)
PUT /api/admin/auth/users

Create a new user

POST /api/admin/auth/users/(name)
POST /api/admin/auth/users

Change user password

DELETE /api/admin/auth/users/(name)
DELETE /api/admin/auth/users

Delete a user

GET /api/admin/auth/users/(name)
GET /api/admin/auth/users

Returns a list of users

GET method provided by the webservice.

Returns:Users
DELETE /api/admin/me/session/(id)
DELETE /api/admin/me/session

Delete a given session

Note: id is mandatory

GET /api/admin/me/session/(id)
GET /api/admin/me/session

Returns a list of sessions

GET method provided by the webservice.

Returns:Sessions
PUT /api/preferences/ui

Create prefs

POST /api/preferences/ui

Change prefs

DELETE /api/preferences/ui

Delete prefs

GET /api/preferences/ui

Returns a list of prefs

GET method provided by the webservice.

Returns:prefs
POST /api/settings/(server)/server-config/(path: conf)
POST /api/settings/(server)/server-config
POST /api/settings/server-config/(path: conf)
POST /api/settings/server-config

Saves the server configuration

GET /api/settings/(server)/server-config/(path: conf)
GET /api/settings/(server)/server-config
GET /api/settings/server-config/(path: conf)
GET /api/settings/server-config

Reads the server configuration

GET method provided by the webservice.

The JSON returned is:

{
  "boolean": [
    "daemon",
    "fork",
    "..."
  ],
  "defaults": {
    "address": "",
    "autoupgrade_dir": "",
    "ca_burp_ca": "",
    "ca_conf": "",
    "ca_name": "",
    "ca_server_name": "",
    "client_can_delete": true,
    "...": "..."
  },
  "integer": [
    "port",
    "status_port",
    "..."
  ],
  "multi": [
    "keep",
    "restore_client",
    "..."
  ],
  "placeholders": {
    "autoupgrade_dir": "path",
    "ca_burp_ca": "path",
    "ca_conf": "path",
    "ca_name": "name",
    "ca_server_name": "name",
    "client_can_delete": "0|1",
    "...": "..."
  },
  "results": {
    "boolean": [
      {
        "name": "hardlinked_archive",
        "value": false
      },
      {
        "name": "syslog",
        "value": true
      },
      { "...": "..." }
    ],
    "clients": [
      {
        "name": "testclient",
        "value": "/etc/burp/clientconfdir/testclient"
      }
    ],
    "common": [
      {
        "name": "mode",
        "value": "server"
      },
      {
        "name": "directory",
        "value": "/var/spool/burp"
      },
      { "...": "..." }
    ],
    "includes": [],
    "includes_ext": [],
    "integer": [
      {
        "name": "port",
        "value": 4971
      },
      {
        "name": "status_port",
        "value": 4972
      },
      { "...": "..." }
    ],
    "multi": [
      {
        "name": "keep",
        "value": [
          "7",
          "4"
        ]
      },
      { "...": "..." }
    ]
  },
  "server_doc": {
    "address": "Defines the main TCP address that the server listens on. The default is either '::' or '0.0.0.0', dependent upon compile time options.",
    "...": "..."
  },
  "string": [
    "mode",
    "address",
    "..."
  ],
  "suggest": {
    "compression": [
      "gzip1",
      "gzip2",
      "gzip3",
      "gzip4",
      "gzip5",
      "gzip6",
      "gzip7",
      "gzip8",
      "gzip9"
    ],
    "mode": [
      "client",
      "server"
    ],
    "...": []
  }
}
Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
Returns:

The JSON described above.

GET /api/settings/(server)/path-expander/(client)
GET /api/settings/(server)/path-expander
GET /api/settings/path-expander/(client)
GET /api/settings/path-expander

Expends a given path

For instance if it’s given a glob expression it will returns a list of files matching the expression.

GET /api/settings/(server)/clients
GET /api/settings/clients

Returns a list of clients

GET /api/settings/(server)/options
GET /api/settings/options

Returns various setting options

PUT /api/settings/(server)/config
PUT /api/settings/config

Creates a new client

GET /api/clients/(server)/backup-running
GET /api/clients/backup-running

Tells if a backup is running right now

GET method provided by the webservice.

The JSON returned is:

{
    "running": false
}

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
Returns:

The JSON described above.

GET /api/clients/(server)/running/(client)
GET /api/clients/(server)/running
GET /api/clients/running/(client)
GET /api/clients/running

Returns a list of clients currently running a backup

GET method provided by the webservice.

The JSON returned is:

[ 'client1', 'client2' ]

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to see.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • client (str) – Ask a specific client in order to know if it is running a backup
Returns:

The JSON described above.

GET /api/servers/report

Returns a global report about all the servers managed by Burp-UI

GET method provided by the webservice.

The JSON returned is:

{
  "backups": [
    {
      "name": "AGENT1",
      "number": 49
    }
  ],
  "servers": [
    {
      "name": "AGENT1",
      "number": {
        "os": {
          "linux": 4
        },
        "total": 349705,
        "totsize": 119400711726,
      }
    }
  ]
}

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients/servers you are authorized to.

Returns:The JSON described above.
GET /api/clients/(server)/report
GET /api/clients/report

Returns a global report about all the clients of a given server

GET method provided by the webservice.

The JSON returned is:

{
  "backups": [
    {
      "name": "client1",
      "number": 15
    },
    {
      "name": "client2",
      "number": 1
    }
  ],
  "clients": [
    {
      "name": "client1",
      "stats": {
        "total": 296377,
        "totsize": 57055793698,
        "os": "unknown"
      }
    },
    {
      "name": "client2",
      "stats": {
        "total": 3117,
        "totsize": 5345361,
        "os": "windows"
      }
    }
  ]
}

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
Returns:

The JSON described above

GET /api/servers/stats

Returns a list of servers (agents) with basic stats

GET method provided by the webservice.

The JSON returned is:

[
  {
    'alive': true,
    'clients': 2,
    'name': 'burp1',
  },
  {
    'alive': false,
    'clients': 0,
    'name': 'burp2',
  },
]
Returns:The JSON described above.
GET /api/clients/(server)/stats
GET /api/clients/stats

Returns a list of clients with their states

GET method provided by the webservice.

The JSON returned is:

{
  [
    {
      "last": "2015-05-17 11:40:02",
      "name": "client1",
      "state": "idle",
      "phase": "phase1",
      "percent": 12,
    },
    {
      "last": "never",
      "name": "client2",
      "state": "idle",
      "phase": "phase2",
      "percent": 42,
    }
  ]
}

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
Returns:

The JSON described above

GET /api/clients/(server)/all
GET /api/clients/all

Returns a list of all clients with their associated Agent if any

GET method provided by the webservice.

The JSON returned is:

[
  {
    "name": "client1",
    "agent": "agent1"
  },
  {
    "name": "client2",
    "agent": "agent1"
  },
  {
    "name": "client3",
    "agent": "agent2"
  }
]

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
Returns:

The JSON described above

GET /api/admin/me

Returns the current user informations

GET method provided by the webservice.

Returns:Users
GET /api/misc/languages

Returns a list of supported languages

GET method provided by the webservice.

The JSON returned is:

{
  "en": "English",
  "fr": "Français"
}
Returns:The JSON described above.
GET /api/misc/(server)/counters/(client)
GET /api/misc/(server)/counters
GET /api/misc/counters/(client)
GET /api/misc/counters

Returns counters for a given client

GET method provided by the webservice.

Parameters:
  • name – the client name if any. You can also use the GET parameter

‘name’ to achieve the same thing

Returns:Counters
GET /api/misc/(server)/monitor
GET /api/misc/monitor

Returns a list of clients that are currently running a backup

GET method provided by the webservice.

The JSON returned is:

[
  {
    'client': 'client1',
    'agent': 'burp1',
    'counters': {
        'phase': 2,
        'path': '/etc/some/configuration',
        '...': '...',
    },
  },
  {
    'client': 'client12',
    'agent': 'burp2',
    'counters': {
        'phase': 3,
        'path': '/etc/some/other/configuration',
        '...': '...',
    },
  },
]

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
Returns:

The JSON described above

GET /api/misc/(server)/history/(client)
GET /api/misc/history/(client)
GET /api/misc/(server)/history
GET /api/misc/history

Returns a list of calendars describing the backups that have been completed so far

GET method provided by the webservice.

The JSON returned is:

[
  {
    "color": "#7C6F44",
    "events": [
      {
        "backup": "0000001",
        "end": "2015-01-25 13:32:04+01:00",
        "name": "toto-test",
        "start": "2015-01-25 13:32:00+01:00",
        "title": "Client: toto-test, Backup n°0000001",
        "url": "/client/toto-test"
      }
    ],
    "name": "toto-test",
    "textColor": "white"
  }
]

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • client (str) – Which client to collect data from
Returns:

The JSON described above

POST /api/misc/alert

Propagate a message to the next screen (or whatever reads the session)

GET /api/misc/(server)/about
GET /api/misc/about

Returns various informations about Burp-UI

GET /api/swagger.json

Render the Swagger specifications as JSON

GET /api/doc

Override this method to customize the documentation page

POST /api/settings/(server)/config/(client)/(path: conf)
POST /api/settings/config/(client)/(path: conf)
POST /api/settings/(server)/config/(client)
POST /api/settings/config/(client)

Saves a given client configuration

DELETE /api/settings/(server)/config/(client)/(path: conf)
DELETE /api/settings/config/(client)/(path: conf)
DELETE /api/settings/(server)/config/(client)
DELETE /api/settings/config/(client)

Deletes a given client

GET /api/settings/(server)/config/(client)/(path: conf)
GET /api/settings/config/(client)/(path: conf)
GET /api/settings/(server)/config/(client)
GET /api/settings/config/(client)

Reads a given client configuration

PUT /api/restore/(server)/server-restore/(name)/(int: backup)
PUT /api/restore/server-restore/(name)/(int: backup)

Schedule a server-initiated restoration

PUT method provided by the webservice.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
  • backup (int) – The backup we are working on
Returns:

Status message (success or failure)

POST /api/restore/(server)/archive/(name)/(int: backup)
POST /api/restore/archive/(name)/(int: backup)

Performs an online restoration

POST method provided by the webservice. This method returns a flask.Response object.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
  • backup (int) – The backup we are working on
Returns:

A flask.Response object representing an archive of the restored files

GET /api/client/(server)/browseall/(name)/(int: backup)
GET /api/client/browseall/(name)/(int: backup)

Returns a list of all ‘nodes’ of a given backup

GET method provided by the webservice.

The JSON returned is:

[
  {
    "date": "2015-05-21 14:54:49",
    "gid": "0",
    "inodes": "173",
    "selected": false,
    "expanded": false,
    "children": [],
    "mode": "drwxr-xr-x",
    "name": "/",
    "key": "/",
    "title": "/",
    "fullname": "/",
    "parent": "",
    "size": "12.0KiB",
    "type": "d",
    "uid": "0"
  }
]

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
  • backup (int) – The backup we are working on
Returns:

The JSON described above.

GET /api/client/(server)/browse/(name)/(int: backup)
GET /api/client/browse/(name)/(int: backup)

Returns a list of ‘nodes’ under a given path

GET method provided by the webservice.

The JSON returned is:

[
  {
    "date": "2015-05-21 14:54:49",
    "gid": "0",
    "inodes": "173",
    "selected": false,
    "expanded": false,
    "children": [],
    "mode": "drwxr-xr-x",
    "name": "/",
    "key": "/",
    "title": "/",
    "fullname": "/",
    "parent": "",
    "size": "12.0KiB",
    "type": "d",
    "uid": "0"
  }
]

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
  • backup (int) – The backup we are working on
Returns:

The JSON described above.

GET /api/client/(server)/report/(name)/(int: backup)
GET /api/client/(server)/report/(name)
GET /api/client/report/(name)/(int: backup)
GET /api/client/report/(name)

Returns a global report of a given backup/client

GET method provided by the webservice.

The JSON returned is:

{
  "dir": {
    "changed": 0,
    "deleted": 0,
    "new": 394,
    "scanned": 394,
    "total": 394,
    "unchanged": 0
  },
  "duration": 5,
  "efs": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "encrypted": true,
  "end": 1422189124,
  "files": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "files_enc": {
    "changed": 0,
    "deleted": 0,
    "new": 1421,
    "scanned": 1421,
    "total": 1421,
    "unchanged": 0
  },
  "hardlink": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "meta": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "meta_enc": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "number": 1,
  "received": 1679304,
  "softlink": {
    "changed": 0,
    "deleted": 0,
    "new": 1302,
    "scanned": 1302,
    "total": 1302,
    "unchanged": 0
  },
  "special": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "start": 1422189119,
  "total": {
    "changed": 0,
    "deleted": 0,
    "new": 3117,
    "scanned": 3117,
    "total": 3117,
    "unchanged": 0
  },
  "totsize": 5345361,
  "vssfooter": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "vssfooter_enc": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "vssheader": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "vssheader_enc": {
    "changed": 0,
    "deleted": 0,
    "new": 0,
    "scanned": 0,
    "total": 0,
    "unchanged": 0
  },
  "windows": "false"
}

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
  • backup (int) – The backup we are working on
Returns:

The JSON described above.

DELETE /api/restore/(server)/server-restore/(name)
DELETE /api/restore/server-restore/(name)

Remove the ‘restore’ file if present

DELETE method provided by the webservice.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
Returns:

Status message (success or failure)

GET /api/restore/(server)/server-restore/(name)
GET /api/restore/server-restore/(name)

Reads the content of the ‘restore’ file if present

GET method provided by the webservice.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
Returns:

The content of the restore file

PUT /api/backup/(server)/do-server-backup/(name)
PUT /api/backup/do-server-backup/(name)

Schedule a server-initiated backup

PUT method provided by the webservice.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
Returns:

Status message (success or failure)

DELETE /api/backup/(server)/server-backup/(name)
DELETE /api/backup/server-backup/(name)

Remove the ‘backup’ file if present

DELETE method provided by the webservice.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
Returns:

Status message (success or failure)

GET /api/backup/(server)/server-backup/(name)
GET /api/backup/server-backup/(name)

Tells if a ‘backup’ file is present

GET method provided by the webservice.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
Returns:

True if the file is found

GET /api/client/(server)/stats/(name)
GET /api/client/stats/(name)

Returns a list of backups for a given client

GET method provided by the webservice.

The JSON returned is:

[
  {
    "date": "2015-01-25 13:32:00",
    "deletable": true,
    "encrypted": true,
    "received": 123,
    "size": 1234,
    "number": 1
  },
]

The output is filtered by the burpui.misc.acl module so that you only see stats about the clients you are authorized to.

Parameters:
  • server (str) – Which server to collect data from when in multi-agent mode
  • name (str) – The client we are working on
Returns:

The JSON described above.