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:

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