Canopy API
This page introduces you to using and developing REST APIs for Canopy.
Why REST?
Modern web applications are often based on separating the front-end UI code and the backend 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 for Canopy).
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:
- User-based (i.e. 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 (Each API calls requires the token). Each user in Canopy can have a single token associated with them that allows access which their privileges and 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 alpha numeric 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>
Example http header:
Authorization: Token 2cdd70527c03ac18be79fc6a56ab11f857bd2ad9
Example usage via curl to retrieve the list of companies:
curl -v -X GET https://CANOPY_SERVER/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 at Demo API Client.
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: sudo 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.
| API root | Sub-sections | Description |
|---|---|---|
/health/ | N/A | A simple health check for backend services. |
/api/activities/ |
| Provides access to the logged in user's activity log. Predominantly for internal use and UI display. |
| /api/accounts/ |
| Accounts gives the user access to certain information relating to users, roles, and other account (authentication/authorisation/etc.) information 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/ |
| Access to common settings on the server. This root allows you access various settings on the server, including skills, currency, and so on. This 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 elelements. /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 Tech Managers and Administrators. /api/common/frontenderror Used to capture front-end JavaScript errors and return them to the backend 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 Local information. /api/common/log N/A. /api/common/logo Access to the license holders logo, for display in Canopy. /api/common/rating A list of standard rating labels (Info - Critical) used within Canopy. This is not modfiable. /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/ |
| Access to the company objects on the system. Companies can be considered things like clients or internal business units. The root level will provide steps to navigate to company sub-sections. /api/company/company To access a list of companies, navigate to: /company/company/ To access a single company: /company/company/1/ /api/company/company_custo_ 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 company. These are top level files that are stored separately to project data, reports, etc. |
| /api/contact/ |
| Access to the contact objects. Contacts store contact information that is associated with a company 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/ |
| 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 1-many 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/ |
| The phase container is where all of the assessments details are linked to, such as findings, assets, examples and evidence, methodoligies, 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 methodologies available for use within the phase. template_methodology_item A list of methodology items associated with template methodllogies 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 Administration 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/ |
| 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 retreives 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/ |
| 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 Tech Managers and Administrators can manage. /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
| 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/ |
| TODO. 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/ |
| This API endpoint is used for managing ticket trackers and querying data from them. It is managed via the Administration interface, but is accessible via projects. |