diff --git a/docs/declarative-templates.md b/docs/declarative-templates.md index a5483ba24..80ee4fdba 100644 --- a/docs/declarative-templates.md +++ b/docs/declarative-templates.md @@ -25,7 +25,7 @@ Future work: ## Admin Experience Administrators can manage their own templates via `onefuzz job_templates -manage [create,delete,list,update]`. +manage [list,get,update,delete]`. If the runtime configuration for the template changes, users will need to refresh their cache to pull the runtime configuration. @@ -119,6 +119,7 @@ JobTemplateNotification( ) ``` + ## Differences from Existing Templates * Declaratively specifying the allowed values for enums, such as StatsFormat, diff --git a/docs/managing-templates.md b/docs/managing-templates.md new file mode 100644 index 000000000..c3d49ca50 --- /dev/null +++ b/docs/managing-templates.md @@ -0,0 +1,136 @@ +# Managing Declarative Job Templates + +[Declarative Job Templates](declarative-templates.md), currently a preview +feature, allow a user to define a reusable fuzzing pipeline as a template. +Once saved, any user of the OneFuzz instance can create fuzzing jobs based on +the templates. + +This is a walk-through guide for updating an existing job template, though +the process is similar for creating templates from scratch. + +This process demonstrates adding [Microsoft Teams +notifications](notifications/teams.md) for new unique crash reports to an existing +`libfuzzer_linux` job template and saving it as `libfuzzer_with_teams`. + +## Using the CLI & modifying JSON + +1. Enable support for declarative templates. + ``` + onefuzz config --enable_feature job_templates + ``` +2. List available templates. + ``` + onefuzz job_templates list + ```` +3. Save a copy of the template locally. + ``` + onefuzz job_templates manage get libfuzzer_linux > libfuzzer_linux.json + ``` +4. With your preferred text editor, add the following to the notifications list (look for `"notifications": []`): + ```json + { + "container_type": "unique_reports", + "notification": { + "config": { + "url": "https://contoso.com/webhook-url-here" + } + } + } + ``` +5. Upload the template. + ``` + onefuzz job_templates manage upload libfuzzer_with_teams @./libfuzzer_linux.json + ``` + +## Using the SDK + +1. Enable support for declarative templates. + ``` + onefuzz config --enable_feature job_templates + ``` +2. Run the following python + ```python + from onefuzztypes.job_templates import JobTemplateNotification + from onefuzztypes.models import NotificationConfig, TeamsTemplate + from onefuzztypes.enums import ContainerType + from onefuzz.api import Onefuzz + + o = Onefuzz() + template = o.job_templates.manage.get("libfuzzer_linux") + template.notifications.append( + JobTemplateNotification( + container_type=ContainerType.unique_reports, + notification=NotificationConfig( + config=TeamsTemplate(url="https://contoso.com/webhook-url-here") + ), + ) + ) + o.job_templates.manage.upload("libfuzzer_with_teams", template) + ``` + +## Using the updated template + +The OneFuzz SDK caches the list of Declarative Job Templates and will +automatically refresh the templates every 24 hours. As shown below, users can +refresh the declarative job template cache on demand. + +If an existing template is changed without requiring new user input via [form +fields](declarative-templates.md#example-form-fields), using the template can +happen transparently. + +If you create a new template or update an existing template that changes the +user interaction, users will need to refresh their template cache to make use +of the change. + +Now let's make use of our new template. + +1. Update our template cache to make sure we have the latest `libfuzzer_with_teams` template + ``` + $ onefuzz job_templates refresh + WARNING:onefuzz:job_templates are a preview-feature and may change in an upcoming release + INFO:onefuzz:refreshing job template cache + INFO:onefuzz:updated template definition: libfuzzer_linux + INFO:onefuzz:updated template definition: libfuzzer_with_teams + INFO:onefuzz:updated template definition: afl_windows + INFO:onefuzz:updated template definition: afl_linux + INFO:onefuzz:updated template definition: libfuzzer_windows + $ + ``` +2. Launch our job + ``` + $ onefuzz job_templates submit libfuzzer_with_teams example-project example-target build-1 linux --target_exe ./fuzz.exe + WARNING:onefuzz:job_templates are a preview-feature and may change in an upcoming release + INFO:onefuzz:creating container: oft-inputs-88dfb15b9ab758b88b122508d4648687 + INFO:onefuzz:creating container: oft-readonly-inputs-88dfb15b9ab758b88b122508d4648687 + INFO:onefuzz:creating container: oft-no-repro-88dfb15b9ab758b88b122508d4648687 + INFO:onefuzz:creating container: oft-crashes-88dfb15b9ab758b88b122508d4648687 + INFO:onefuzz:creating container: oft-reports-88dfb15b9ab758b88b122508d4648687 + INFO:onefuzz:creating container: oft-unique-reports-88dfb15b9ab758b88b122508d4648687 + INFO:onefuzz:creating container: oft-setup-fde90db8a8e65b4e8b7518f9d1350036 + INFO:onefuzz:uploading ./fuzz.exe to oft-setup-fde90db8a8e65b4e8b7518f9d1350036 + INFO:onefuzz:creating container: oft-coverage-88dfb15b9ab758b88b122508d4648687 + { + "config": { + "build": "build-1", + "duration": 24, + "name": "example-target", + "project": "example-project" + }, + "job_id": "d3259dfe-fdad-45a0-bf90-a381b8dc1ee8", + "state": "init" + } + $ + ``` +3. Verify a notification was set up for the unique reports container + ``` + $ onefuzz notifications list --query "[?container == 'oft-unique-reports-88dfb15b9ab758b88b122508d4648687']" + [ + { + "config": { + "url": "***" + }, + "container": "oft-unique-reports-88dfb15b9ab758b88b122508d4648687", + "notification_id": "0e0c10a1-78ef-4f65-be56-d3ba0788fcb5" + } + ] + ```