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.

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/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/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)/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/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)/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.

API¶

Related Topics

This Page