[DOCS-143] Use case: Create an asset with our API #145
Conversation
✅ Deploy Preview for cobalt-docs ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
content/en/APIUseCases/_index.md
Outdated
| If you add a `| jq .` to the end of your REST call, you may find it easier to | ||
| read the output: | ||
|
|
||
| ``` |
content/en/APIUseCases/_index.md
Outdated
|
|
||
| Without the `| jq.`, you may have output that looks like: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
```json
This highlights the syntax.
| linkTitle: "Create an Asset" | ||
| weight: 110 | ||
| description: > | ||
| Use this sequence of REST calls to create an asset. |
There was a problem hiding this comment.
Send this sequence...
Use is repeated 3 times.
There was a problem hiding this comment.
I'm using "Run this sequence..."
| @@ -0,0 +1,229 @@ | |||
| --- | |||
| title: "Use Our API to Create an Asset" | |||
There was a problem hiding this comment.
Option: Create an Asset via the API
Since we'll add more guides to this section, I would start the title with an action and then add "Using the API" or "via the API." At the same time, if we repeat it in each guide, this will be redundant.
There was a problem hiding this comment.
At the same time, if we repeat it in each guide, this will be redundant.
Good point. Since this book already has API in the name, I'm going to limit such titles -- in this case "Create an Asset"
btw, the Google Developer Style guide suggests that we should not use via
content/en/APIUseCases/_index.md
Outdated
| --- | ||
|
|
||
| {{% pageinfo %}} | ||
| The pages in this book describe how you can use our API to manage your Assets |
There was a problem hiding this comment.
assets
We discussed the capitalization for assets this week.
There was a problem hiding this comment.
| The pages in this book describe how you can use our API to manage your Assets | |
| The pages in this book describe how you can use our API to manage your assets |
content/en/APIUseCases/_index.md
Outdated
| --- | ||
|
|
||
| {{% pageinfo %}} | ||
| The pages in this book describe how you can use our API to manage your Assets |
There was a problem hiding this comment.
Since we'll add more guides to this section (not only about assets or pentests), maybe we can make the sentence more generic? Something like:
The pages in this book describe how you can use our API to interact with the Cobalt platform.
The pages in this book describe how you can work with the Cobalt platform using the API.
| Next, you can use the API Token to authorize access to our other endpoints. Take | ||
| the API Token that you [generated](#create-an-api-token-in-the-cobalt-ui). Substitute that value for `YOUR-PERSONAL-API-TOKEN`: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
```c
With c, the syntax is highlighted properly, but nothing happens when I try curl or cURL.
| <!-- Future task: set up variables for `YOUR-PERSONAL-API-TOKEN` and | ||
| `YOUR-V2-ORGANIZATION-TOKEN`. May support automated populating of REST calls. --> | ||
|
|
||
| This page describes how you can use our API To create an [asset](../../getting-started/glossary/#asset). |
There was a problem hiding this comment.
to
We can remove this sentence, the same information is given earlier.
| {{%expand "Review sample output." %}} | ||
| You should see output similar to: | ||
|
|
||
| ``` |
|
|
||
| You can create an [asset](../getting-started/glossary/#asset) with the following REST call: | ||
|
|
||
| ``` |
| To add or modify or information related to your asset, you'll need the asset ID. | ||
| You can find this ID with the REST call to [Get All Assets](https://docs.cobalt.io/v2/#get-all-assets): | ||
|
|
||
| ``` |
| reference to [Get All Assets](https://docs.cobalt.io/v2/#get-all-assets). | ||
|
|
||
| {{% expand "Review sample output." %}} | ||
| ``` |
| information with the following REST call: | ||
|
|
||
|
|
||
| ``` |
| As an example, the following command uploads the `image.jpg` file as asset | ||
| documentation: | ||
|
|
||
| ``` |
| Save the API Token. After you exit the modal, you won't see the full token again. | ||
| If you lose it, you may have to revoke the token and start over. |
There was a problem hiding this comment.
Save the API token. After you close the overlay, you won't see the full token again.
If you lose it, you may have to revoke the token and start again.
There was a problem hiding this comment.
Will accept. I searched for instances of both, and "close the overlay" is 4x more popular than "exit the modal".
| Save the API Token. After you exit the modal, you won't see the full token again. | ||
| If you lose it, you may have to revoke the token and start over. | ||
|
|
||
| Substitute the API Token for `YOUR-PERSONAL-API-TOKEN` in the REST calls |
| Next, you can use the API Token to authorize access to our other endpoints. Take | ||
| the API Token that you [generated](#create-an-api-token-in-the-cobalt-ui). Substitute that value for `YOUR-PERSONAL-API-TOKEN`: |
There was a problem hiding this comment.
Next, you can use the API token to authorize in the Cobalt API. Take
the API token that you generated. Substitute that value for YOUR-PERSONAL-API-TOKEN:
There was a problem hiding this comment.
FWIW, when I disable 2FA for an account, I've found REST calls to sign in and create an API token. But, those REST calls are not part of the Cobalt API. So I'm going to change this to
...
Next, you can use the API token to authorize access to the Cobalt API. Take
the API token that you generated. Substitute that value for YOUR-PERSONAL-API-TOKEN:
| { | ||
| "resource": { | ||
| "id": "some_id", | ||
| "name": "Saxophone - Alto", |
There was a problem hiding this comment.
In the ideal world, we should have an organization to use in examples, such as Example Organization.
There was a problem hiding this comment.
Oh gosh -- I really should change this to something that sounds more serious!
| -v | ||
| ``` | ||
|
|
||
| For more information on each parameter, see our API Reference documentation on |
| how to [Create an Asset](https://docs.cobalt.io/v2/#create-an-asset). | ||
|
|
||
| The command we use includes a `-v`, which sets up output in verbose mode. The | ||
| command works without it; however, you would see no response from the REST call. |
There was a problem hiding this comment.
command works without it. However, you would see no response from the REST call.
| | Message | Meaning | | ||
| |------------|------------------| | ||
| | HTTP/2 201 | Asset created | | ||
| | HTTP/2 401 | No asset created. Check the value of your API Token| |
There was a problem hiding this comment.
I'm thinking -- maybe we should PR the API reference to include this list (and rename Errors to "HTTP responses" or "HTTP response codes"
| |------------|------------------| | ||
| | HTTP/2 201 | Asset created | | ||
| | HTTP/2 401 | No asset created. Check the value of your API Token| | ||
| | HTTP/2 404 | No asset created. Check the value of YOUR-V2-ORGANIZATION-TOKEN| |
There was a problem hiding this comment.
YOUR-V2-ORGANIZATION-TOKEN
I also get 422 when enter an invalid org token.
|
|
||
| ## Find Your Asset ID | ||
|
|
||
| To add or modify or information related to your asset, you'll need the asset ID. |
There was a problem hiding this comment.
To add or modify the information
| If you've set up more than one Asset, you may need to search through the output. | ||
| For more information about each Asset response field, see our API documentation | ||
| reference to [Get All Assets](https://docs.cobalt.io/v2/#get-all-assets). | ||
|
|
There was a problem hiding this comment.
If your organization has more than 10 assets, you can add the limit parameter to the request URL to retrieve more entries.
There was a problem hiding this comment.
I might set that up as a separate note
There was a problem hiding this comment.
I've addressed this in current lines 136-139
(You can use limit with any number -- the link includes "5" as an example:
"If specified, returns only a specified amount of assets, e.g. https://api.cobalt.io/assets?limit=5"
| -H "Accept: application/vnd.cobalt.v2+json" \ | ||
| -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ | ||
| -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \ | ||
| | jq . |
There was a problem hiding this comment.
We can also filter assets by their title and id by adding the following jq command:
| jq -r ".data[] | .resource | .title, .id"
There was a problem hiding this comment.
Whoa! I didn't know this!
There was a problem hiding this comment.
I'm not an expert on this topic. I will educate myself more on jq. Some responses are too long to include them in documentation, so this can be beneficial.
There was a problem hiding this comment.
There should be a way to retrieve an ID for a specific asset by its name, but I don't know the syntax for this command. 🙁
There was a problem hiding this comment.
MVC. Your suggestion is an improvement over mine.
FWIW, I've set up your suggestion as a "tip", current lines 141-144
| {{% /expand %}} | ||
|
|
||
| If you've set up more than one asset, you'll see the `id` in the same | ||
| code block as the `title`, which you may have used to [create the asset](#create-an-asset). |
There was a problem hiding this comment.
object as the title
|
|
||
| | Message | Meaning | | ||
| |------------|------------------| | ||
| | HTTP/2 201 | Asset created | |
There was a problem hiding this comment.
| HTTP/2 204 | Asset updated |
|
|
||
| ## Include an Asset Attachment | ||
|
|
||
| You can help our pentesters by including images or even PDFs. As noted in our |
There was a problem hiding this comment.
Maybe it's time to set up another variable, to list the same attachments on this page, and in https://developer.cobalt.io/getting-started/assets/asset-description/
| ## Include an Asset Attachment | ||
|
|
||
| You can help our pentesters by including images or even PDFs. As noted in our | ||
| [Asset Documentation](../getting-started/assets/asset-description/#asset-documentation), |
There was a problem hiding this comment.
(../../getting-started/assets/asset-description/#asset-documentation)
|
@ana-dashuk-cobalt thanks so much for your detailed review. I'm going to push an update that addresses most of your questions. But first, I'm going to add comments when I don't agree with something. (And I need to research the list of supported languages for code -- I think of For a C language code sample, ref https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers |
|
Hugo has a list of "lexers" https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages. Based on that list,```bash seems to work better. |
|
@ana-dashuk-cobalt once you've given your "OK" to this, I'm going to set up a new PR for developer review(s). We might reorganize this later. Examples:
|
| ```json | ||
| { | ||
| "data": { | ||
| "resource": { | ||
| "id": "YOUR-ASSET-IDENTIFIER", | ||
| "title": "Test Asset", | ||
| "description": "How to describe the asset to our pentesters", | ||
| "asset_type": "web", | ||
| "logo": null, | ||
| "attachments": [] | ||
| }, | ||
| "links": { | ||
| "ui": { | ||
| "url": "https://api.cobalt.io/links/<endpoint for the asset>" | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
| ```json | |
| { | |
| "data": { | |
| "resource": { | |
| "id": "YOUR-ASSET-IDENTIFIER", | |
| "title": "Test Asset", | |
| "description": "How to describe the asset to our pentesters", | |
| "asset_type": "web", | |
| "logo": null, | |
| "attachments": [] | |
| }, | |
| "links": { | |
| "ui": { | |
| "url": "https://api.cobalt.io/links/<endpoint for the asset>" | |
| } | |
| } | |
| } | |
| } |
YOUR-ASSET-TITLE
YOUR-ASSET-IDENTIFIER
There was a problem hiding this comment.
I chose "Test Asset" to match the name I used to create the asset.
Co-authored-by: ana-dashuk-cobalt <[email protected]>
@ana-dashuk-cobalt I'd appreciate your thoughts on my first draft. Is it understandable? Would you be able to use it?
I think I want to update / add several things, including:
Possibly: