Add more concepts

caido · Dec 19, 2024 · 351dbd0 · 351dbd0
1 parent 24ccde9
commit 351dbd0
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 27 deletions.
diff --git a/.vitepress/sidebars/concepts.ts b/.vitepress/sidebars/concepts.ts
@@ -26,6 +26,10 @@ export const conceptsSidebar: DefaultTheme.SidebarItem[] = [
         text: "Dealing with Binary",
         link: "/concepts/backend/binary",
       },
+      {
+        text: "Difference with workflows",
+        link: "/concepts/backend/workflow",
+      },
     ],
   },
   {

diff --git a/src/_images/backend_plugin_starter.png b/src/_images/backend_plugin_starter.png
diff --git a/src/_images/workflow_editor.png b/src/_images/workflow_editor.png
diff --git a/src/concepts/backend/workflow.md b/src/concepts/backend/workflow.md
@@ -0,0 +1,27 @@
+# Backend Plugins vs Workflows
+
+You might be wondering what is the differences between a workflow and a backend plugin.
+We are aware that the two concept might be confusing since both give you scripting access to Caido and generally expose the same functionalities.
+But they serve different purposes.
+
+## Workflow
+
+Workflows are our low-code/no-code solution. You should generally start with them if you need to extend Caido.
+The pre-made nodes use under the hood the [workflow SDK](/reference/sdks/workflow/) of Caido.
+Workflows run on-demand, they don't persist in between runs. They are similar in concept to Lambdas or Functions as a Service system.
+
+When using the Javascript nodes, you have a full access to the [workflow SDK](/reference/sdks/workflow/).
+The [runtime](/concepts/essentials/runtime) for that Javascript code is the same as for the backend plugins, but the SDK has access to less functionalities.
+This is why it is easy to start with a workflow using Javascript nodes and then transition to a backend plugin.
+
+<img alt="Workflow editor" src="/_images/workflow_editor.png" width="800" center/>
+
+## Backend plugins
+
+Backend plugins gives you a long running thread inside Caido that uses our Javascript [runtime](/concepts/essentials/runtime).
+It can use the [backend SDK](/reference/sdks/backend/) which is similar to the [workflow SDK](/reference/sdks/workflow/), but with more features.
+For example, it can expose an API that a `frontend plugin` can use.
+
+Generally if your intent is to create an interface in Caido (via a `frontend plugin`), you will need a `backend plugin` to go with it.
+
+<img alt="Backend plugin starterkit code" src="/_images/backend_plugin_starter.png" width="700" center/>
diff --git a/src/concepts/index.md b/src/concepts/index.md
@@ -15,6 +15,7 @@ Here you will find explanations of the core concepts that underpin Caido plugins
 - [Plugin Architecture](./essentials/package.md) - The structure of a plugin package.
 - [Tooling](./essentials/tooling.md) - Tools for the ease of plugin development.
 - [Runtime](./essentials/runtime.md) - Javascript runtimes used by plugins.
+- [Signing](./essentials/signing.md) - Plugin signing.
 
 ## Modules
 

diff --git a/src/reference/manifest.md b/src/reference/manifest.md
@@ -30,6 +30,12 @@ The `manifest.json` file is the first file that is read by the Caido application
       "name": "Authmatrix Backend",
       "runtime": "javascript",
       "entrypoint": "backend/script.js"
+    },
+    {
+      "kind": "workflow",
+      "id": "authmatrix-workflow",
+      "name": "Authmatrix Workflow",
+      "definition": "workflow/definition.json"
     }
   ]
 }
@@ -39,50 +45,59 @@ Here's a summary of each field (**required** fields are marked with an asterisk
 
 ## Main Fields
 
-Field|Description
----|---
-id*|Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)*$`_).
-version*|The version of your plugin package. Follows the `MAJOR.MINOR.PATCH` syntax.
-name|The name of your plugin package. If not supplied, the `id` will be used as the `name`.
-description|A description of the plugin.
+| Field       | Description                                                                                                                                                                                            |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| id\*        | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`\_). |
+| version\*   | The version of your plugin package. Follows the `MAJOR.MINOR.PATCH` syntax.                                                                                                                            |
+| name        | The name of your plugin package. If not supplied, the `id` will be used as the `name`.                                                                                                                 |
+| description | A description of the plugin.                                                                                                                                                                           |
 
 ## Author Fields
 
 The `author` field is optional and may be used for crediting purposes.
 
-Field|Description
----|---
-name|The name of the author.
-email|The email address of the author.
-url|A URL to the author's website.
+| Field | Description                      |
+| ----- | -------------------------------- |
+| name  | The name of the author.          |
+| email | The email address of the author. |
+| url   | A URL to the author's website.   |
 
 ## Plugins Fields
 
 The `plugins` field is required and must contain an array of plugins.
 
-Plugins can be of type `frontend` or `backend`.
+Plugins can be of type `frontend`, `backend` or `workflow`.
 
 ::: tip
 You can define multiple plugins of the same type. For example, you can define 3 different frontend plugins that will interact with the same backend plugin.
 :::
 
 ### Frontend Plugins
 
-Field|Description
----|---
-kind*| Must be of type `frontend`
-id*|Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)*$`).
-entrypoint*|Specifies the location of the primary script to be executed when the plugin is launched.
-name|The cosmetic plugin package name displayed in the [Plugins](https://docs.caido.io/reference/features/workspace/plugins.html) table. If not supplied, the `id` will be used as the `name`.
-style|Specifies the location of the CSS file to be used to stylize elements of your plugin.
-backend|This object contains the `id` of the associated backend plugin. Specifying this field will allow the frontend plugin to communicate with the backend plugin via [sdk.backend](/reference/sdks/frontend/#backend).
+| Field        | Description                                                                                                                                                                                                       |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| kind\*       | Must be of type `frontend`                                                                                                                                                                                        |
+| id\*         | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`).              |
+| entrypoint\* | Specifies the location of the primary script to be executed when the plugin is launched.                                                                                                                          |
+| name         | The cosmetic plugin package name displayed in the [Plugins](https://docs.caido.io/reference/features/workspace/plugins.html) table. If not supplied, the `id` will be used as the `name`.                         |
+| style        | Specifies the location of the CSS file to be used to stylize elements of your plugin.                                                                                                                             |
+| backend      | This object contains the `id` of the associated backend plugin. Specifying this field will allow the frontend plugin to communicate with the backend plugin via [sdk.backend](/reference/sdks/frontend/#backend). |
 
 ### Backend Plugins
 
-Field|Description
----|---
-kind*| Must be of type `backend`
-id*|Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)*$`).
-entrypoint*|Specifies the location of the primary script to be executed when the plugin is launched.
-runtime*|Specifies that JavaScript code will be executed.
-name|The name of your plugin. If not supplied, the `id` will be used as the `name`.
+| Field        | Description                                                                                                                                                                                          |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| kind\*       | Must be of type `backend`                                                                                                                                                                            |
+| id\*         | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`). |
+| entrypoint\* | Specifies the location of the primary script to be executed when the plugin is launched.                                                                                                             |
+| runtime\*    | Specifies that JavaScript code will be executed.                                                                                                                                                     |
+| name         | The name of your plugin. If not supplied, the `id` will be used as the `name`.                                                                                                                       |
+
+### Workflow Plugins
+
+| Field        | Description                                                                                                                                                                                          |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| kind\*       | Must be of type `workflow`                                                                                                                                                                           |
+| id\*         | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`). |
+| definition\* | Specifies the location of workflow json definition.                                                                                                                                                  |
+| name         | The name of your plugin. If not supplied, the `id` will be used as the `name`.                                                                                                                       |