REST API

This page introduces you to using and consuming Canopy’s REST API.

Why REST?

Modern web applications are often based on separating the front-end UI code and the back-end services, and ensuring proper communication using the various HTTP methods as they were intended for. Canopy adopts a (mostly) REST based approach to its own API, and we are happy for our users to develop against our API. This provides a language-agnostic way of integrating with Canopy, as an alternative to using the python interface (see Writing plugins).

Our API is stable in the sense that we try to avoid breaking changes where possible. Advanced warning will be provided where breaking changes are likely to occur to allow our users to determine the impact against their own API integrations. However, if we find that we need to make more frequent API changes in the future, we will fork development of a more stable API-specific server which will be preferred over our internal API.

Authentication

Currently, we can support the following authentication types:

We recommend that all communications with the API server be conducted over HTTPS.

Token based authentication

Token authentication uses a header field containing a token to authenticate API users on a per call basis (the token must be included in each API call). Each user in Canopy can have a single token associated with them that allows access with their privileges. The token does not expire.

To generate a token for a user execute the following on the Canopy server as the canopy user:

canopy-manage drf_create_token USER_EMAIL_ADDRESS

This will generate a 40 character alphanumeric token which can be used to perform API actions for the associated user.

For token based authentication the Authorization HTTP header should have the value Token GENERATED_TOKEN.

Header field name: Authorization

Header field value: Token<SPACE><GENERATED_TOKEN>

Putting them together, an example HTTP header looks like this: Authorization: Token 2cdd70527c03ac18be79fc6a56ab11f857bd2ad9

Example usage via curl to retrieve the list of clients (historically referred to as Companies):

curl -v -X GET https://CANOPY/api/company/company/ -H 'Authorization: Token 2cdd70527c03ac18be79fc6a56ab11f857bd2ad9'

Example usage via Python and the requests library:

import requests

res = requests.get(
    'http://127.0.0.1:8000/api/company/company/',
    headers=dict(
        Authorization='Token 2cdd70527c03ac18be79fc6a56ab11f857bd2ad9'
    )
)
print res.json()

Unlike user-based session authentication, no CSRF token or session ID is required for token based authentication.

Demo API integration

A demo API client is available here: demo_api_client.py

API reference

Canopy ships with a browsable API interface, which is self documenting and provides test forms for invoking different API methods (GET, POST, PUT, DELETE, etc., depending on the permissions of the user).

You can enable the browsable API interface by adding the following configuration line to /etc/canopy/canopy.ini:

ENABLE_API_BROWSER=1

And then restarting Canopy:

systemctl restart canopy

Warning

This configuration is NOT recommended for production use.

Canopy’s API is grouped into a set of top-level roots, with each one providing access to a number of related sub-sections.

API root

Sub-sections

Description

/health/

N/A

A simple health check for back-end services.

/api/activities/

  • entry

  • entry_object

Provides access to the logged in user’s activity log. Predominantly for internal use and UI display.

/api/accounts/

  • custom_roles

  • permissions

  • profile

  • skills

  • allgrants

  • status

  • user

  • accesscontrol

Accounts gives the user access to certain information relating to users, roles, and other account information (authentication, authorisation, etc.) on the system. This data is restricted based on the user’s permissions. For example, a standard user can list user account information. However, they cannot modify it.

custom_roles

API to list and manage (with sufficient privileges) custom (i.e. user defined) roles defined on the system.

permissions

API to list all permissions available on Canopy.

profile

API to list and manage the user’s profile.

skills

API to list and manage skills available on the system, which users can link to their profile.

allgrants

API to list all assigned privileges on the system (useful for debugging).

status

Status feedback on the logged in user.

user

API to list and manage users on the system.

accesscontrol

Used for driving access control settings/updates for various UI components based on the user’s access profile.

/api/common/

  • attackclass

  • backup (DEPRECATED)

  • category

  • compliance (DEPRECATED)

  • currency

  • frontenderror

  • industry

  • license

  • locale

  • log (placeholder)

  • logo

  • rating

  • setting

  • skill

  • substitutionvariable

  • tool

  • toolresult

  • workflowstate

Access to common settings on the server. This root allows you access various settings on the server, including skills, currency, and so on. These are global values for use in other sections of the application. Write access is based on user permissions. The root level provides a list of all global configuration elements.

/api/common/attackclass

The list of attack classes defined via the admin section and used to classify findings / KB findings. This list can be read by anyone, but is managed by Administrators.

/api/common/category

The list of categories defined via the admin section and used to group attack classes together. This list can be read by anyone, but is managed by Administrators.

/api/common/currency

A list of currencies supported by Canopy. This list can be read by anyone, but is managed by Technical Managers and Administrators.

/api/common/frontenderror

Used to capture front-end JavaScript errors and return them to the back-end for logging.

/api/common/industry

A list of company industries. This list can be read by anyone, but is managed by Administrators.

/api/common/license

License information about the installed Canopy instance.

/api/common/locale

Locale information.

/api/common/log

N/A.

/api/common/logo

Access to the license holder’s logo, for display in Canopy.

/api/common/rating

A list of standard rating labels (Info - Critical) used within Canopy. This is not modifiable.

/api/common/setting

A list of global settings. This list can be read by anyone, but is managed by Administrators.

/api/common/skill

Used to list the available skills that users can associate with their user profile.

/api/common/substitutionvariable

A list of supported substitution variables.

/api/common/tool

A list of supported tools.

/api/common/toolresult

A list of imported tool result ID information.

/api/common/workflowstate

A list of workflow states for use in the application.

/api/company/

  • company

  • company_custom_field

  • files

Access to the client objects on the system. Clients can be considered things like companies or internal business units. The root level will provide steps to navigate to client sub-sections.

/api/company/company

To access a list of clients (historically referred to as companies), navigate to:

/company/company/

To access a single client:

/company/company/1/

/api/company/company_custom_field

This lists the custom fields defined on the company model. Used for building the custom sections of the UI layouts.

/api/company/files

A list of files associated with a client. These are top level files that are stored separately to project data, reports, etc.

/api/contact/

  • contact

Access to the contact objects. Contacts store contact information that is associated with a client and can be related to a project, opportunity, phase, etc.

/api/contact/contact

To access the list of contacts, navigate to:

/api/contact/contact/

To access a single contact:

/api/contact/contact/1/

/api/projects/

  • project

  • project_custom_field

Access to the project objects. Projects are used to group phases together. They’re a lightweight container.

project

To access the list of all projects, navigate to:

/api/projects/project/

To access a single contact:

/api/projects/project/1/

Note: a project is a container for one or more phases. To access a phase and its details, see the phases endpoint.

project_custom_field

A list of custom fields defined on the project model. Used for building the custom field sections of the UI layouts.

/api/phases/

  • template_methodology

  • template_methodology_item

  • methodology

  • methodology_item

  • phase

  • phase_custom_field

  • finding

  • upload

  • asset

  • example

  • finding_custom_field

  • finding_reference

  • tool_field_mapping

The phase container is where all of the assessments details are linked to, such as findings, assets, examples and evidence, methodologies, etc.

/api/phases/phase

To list all phases:

/api/phases/phase/

To view/manage a single phase:

/api/phases/phase/1/

template_methodology

A list of methodology templates available for use within the phase.

template_methodology_item

A list of methodology template items associated with methodology templates available for use.

methodology

A list of methodologies associated with the phase.

methodology_item

A list of specific methodology items associated with methodologies that have been linked to a phase.

phase_custom_field

List custom fields associated with the phase model. Managed via the admin interface.

finding

List and work with findings associated with a phase.

upload

Upload files to a phase.

asset

List and manage assets associated with a phase.

example

List and manage examples associated with a phase.

finding_custom_field

List custom fields associated with the finding model. These are managed via the administration section.

finding_reference

List and manage finding references associated with findings of a phase.

tool_field_mapping

List tool fields and their mappings.

/api/reports/

  • content

  • generated_report

  • report

  • tablerow

  • version

The reports endpoint gives access to all reports on the system - restricted by access controls.

/api/reports/report

To list all reports:

/reports/report/

To request a specific report:

/reports/report/1/

/api/reports/content

For content fields (i.e. non-table data), this is used to list the fields and their content for arrangement in the report layout.

/api/reports/generated_report

This end point retrieves generated documents, which have been generated from the report object.

/api/reports/tablerow

For tables stored in reports, this is where the content is stored. Used for arranging table data in the report layout.

/api/reports/version

Version history table associated with each report. This is managed by report authors and also by the workflows.

/api/templates/

  • finding

  • finding_reference

  • document

  • content

  • tablerow

  • documentupload

  • taxonomy

  • taxonomy_item

A number of different template management interfaces. Template content is a big part of Canopy’s proposal to save time and ensure consistency. This section is used to manage all template information. Access in general is open to users for read purposes, but only Technical Managers and Administrators can manage it.

/api/templates/finding

/api/templates/finding_reference

/api/templates/document

/api/templates/content

/api/templates/tablerow

/api/templates/documentupload

/api/templates/taxonomy

/api/templates/taxonomy_item

/api/scheduler/

BETA

  • events

  • resources

  • userresources

Development against this API at the moment is not recommended.

/api/scheduler/events

Manage and list events associated with the scheduler.

/api/scheduler/resources

Manage and list resources associated with the schedule.

/api/scheduler/userresources

Manage and list user resources associated with the schedule.

/api/messaging/

Not supported

Messaging API, predominantly for internal use within Canopy.

/api/workflows/

Not supported

Workflow event API, predominantly for internal use within Canopy.

/api/analytics/ (experimental)

Experimental. Do not use.

Experimental API being used to generate analytics data in Excel format. This should not be developed against.

/api/opportunities/

  • opportunity

  • questionnaire

  • questionnairequestion

  • scopequestion

  • scope

  • scopefile

  • sow

  • sowcontent

  • sowtablerow

  • sowversion

  • tariff

opportunity

questionnaire

questionnairequestion

scopequestion

scope

scopefile

sow

sowcontent

sowtablerow

sowversion

tariff

/api/portals/ (experimental)

Experimental. Do not use.

This is the initial MVP version of the portal API, which is used for pushing Canopy data into a “secure portal” (e.g. for publishing on the internet). This functionality is under development and should not be used.

/api/tickettrackers/

  • tickettracker

  • tickets

This API endpoint is used for managing ticket trackers and querying data from them. It is managed via the admin interface, but is accessible via projects.