This page introduces you to using and consuming Canopy’s REST API.
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.
Currently, we can support the following authentication types:
HTTP “Basic” authentication (username and password)
Token based authentication
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-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
Header field name:
Header field value:
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.
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
And then restarting Canopy:
systemctl restart canopy
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.
A simple health check for back-end services.
Provides access to the logged in user’s activity log. Predominantly for internal use and UI display.
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.
API to list and manage (with sufficient privileges) custom (i.e. user defined) roles defined on the system.
API to list all permissions available on Canopy.
API to list and manage the user’s profile.
API to list and manage skills available on the system, which users can link to their profile.
API to list all assigned privileges on the system (useful for debugging).
Status feedback on the logged in user.
API to list and manage users on the system.
Used for driving access control settings/updates for various UI components based on the user’s access profile.
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.
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.
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.
A list of currencies supported by Canopy. This list can be read by anyone, but is managed by Technical Managers and Administrators.
A list of company industries. This list can be read by anyone, but is managed by Administrators.
License information about the installed Canopy instance.
Access to the license holder’s logo, for display in Canopy.
A list of standard rating labels (Info - Critical) used within Canopy. This is not modifiable.
A list of global settings. This list can be read by anyone, but is managed by Administrators.
Used to list the available skills that users can associate with their user profile.
A list of supported substitution variables.
A list of supported tools.
A list of imported tool result ID information.
A list of workflow states for use in the application.
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.
To access a list of clients (historically referred to as companies), navigate to:
To access a single client:
This lists the custom fields defined on the company model. Used for building the custom sections of the UI layouts.
A list of files associated with a client. These are top level files that are stored separately to project data, reports, etc.
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.
To access the list of contacts, navigate to:
To access a single contact:
Access to the project objects. Projects are used to group phases together. They’re a lightweight container.
To access the list of all projects, navigate to:
To access a single contact:
Note: a project is a container for one or more phases. To access a phase and its details, see the phases endpoint.
A list of custom fields defined on the project model. Used for building the custom field sections of the UI layouts.
The phase container is where all of the assessments details are linked to, such as findings, assets, examples and evidence, methodologies, etc.
To list all phases:
To view/manage a single phase:
A list of methodology templates available for use within the phase.
A list of methodology template items associated with methodology templates available for use.
A list of methodologies associated with the phase.
A list of specific methodology items associated with methodologies that have been linked to a phase.
List custom fields associated with the phase model. Managed via the admin interface.
List and work with findings associated with a phase.
Upload files to a phase.
List and manage assets associated with a phase.
List and manage examples associated with a phase.
List custom fields associated with the finding model. These are managed via the administration section.
List and manage finding references associated with findings of a phase.
List tool fields and their mappings.
The reports endpoint gives access to all reports on the system - restricted by access controls.
To list all reports:
To request a specific report:
For content fields (i.e. non-table data), this is used to list the fields and their content for arrangement in the report layout.
This end point retrieves generated documents, which have been generated from the report object.
For tables stored in reports, this is where the content is stored. Used for arranging table data in the report layout.
Version history table associated with each report. This is managed by report authors and also by the workflows.
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.
Development against this API at the moment is not recommended.
Manage and list events associated with the scheduler.
Manage and list resources associated with the schedule.
Manage and list user resources associated with the schedule.
Messaging API, predominantly for internal use within Canopy.
Workflow event API, predominantly for internal use within Canopy.
Experimental. Do not use.
Experimental API being used to generate analytics data in Excel format. This should not be developed against.
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.
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.