Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Security Solution] Webhook - Case Management Connector Documentation #137726

Merged
merged 31 commits into from
Aug 12, 2022

Conversation

stephmilovic
Copy link
Contributor

@stephmilovic stephmilovic commented Aug 1, 2022

Summary

Documentation for Webhook - Case Management Connector

Preview

@stephmilovic stephmilovic added release_note:skip Skip the PR/issue when compiling release notes Team:ResponseOps Label for the ResponseOps team (formerly the Cases and Alerting teams) Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. auto-backport Deprecated - use backport:version if exact versions are needed Team:Threat Hunting:Explore v8.4.0 v8.5.0 labels Aug 1, 2022
@stephmilovic stephmilovic requested review from a team as code owners August 1, 2022 15:39
@elasticmachine
Copy link
Contributor

Pinging @elastic/security-solution (Team: SecuritySolution)

@elasticmachine
Copy link
Contributor

Pinging @elastic/response-ops (Team:ResponseOps)

@stephmilovic
Copy link
Contributor Author

@lcawl I used gifs for the images, not sure if that is allowed or how to preview so I'm not sure how it looks?

@nastasha-solomon
Copy link
Contributor

nastasha-solomon commented Aug 1, 2022

@stephmilovic you should be able to see how the gifs turned out in the doc build HTML preview. It looks like these errors are preventing the doc build from successfully completing though:

11:49:14 INFO:build_docs:asciidoctor: WARNING: management/connectors/action-types/cases-webhook.asciidoc: line 12: id assigned to block already in use: webhook-connector-configuration
11:49:14 INFO:build_docs:asciidoctor: WARNING: management/connectors/action-types/cases-webhook.asciidoc: line 94: id assigned to block already in use: webhook-connector-networking-configuration
11:49:14 INFO:build_docs:asciidoctor: WARNING: management/connectors/action-types/cases-webhook.asciidoc: line 100: id assigned to block already in use: Preconfigured-webhook-configuration
11:49:14 INFO:build_docs:asciidoctor: WARNING: management/connectors/action-types/cases-webhook.asciidoc: line 158: id assigned to block already in use: define-webhook-ui
11:49:14 INFO:build_docs:asciidoctor: WARNING: management/connectors/action-types/cases-webhook.asciidoc: line 172: id assigned to block already in use: webhook-action-configuration

I searched the kibana project for these anchors and found that they're already used in this existing file. I'm not familiar with this connector though, so I can't tell you too much about the doc (i.e. when it was created, why, etc.).

Copy link
Contributor

@YulNaumenko YulNaumenko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Thank you for the changes.

Copy link
Contributor

@nastasha-solomon nastasha-solomon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left some initial comments and suggestions for your consideration. It looks as though we'll need to tweak the TOC a bit to correct the hierarchy - I can help with that when I'm back from PTO next week. Thanks for writing this up @stephmilovic !

Password:: Password for HTTP basic authentication.
Headers:: A set of key-value pairs sent as headers with the request URLs for the create case, update case, get case, and create comment methods.
Create Case Method:: REST API HTTP request method to create case in third party system, either `post`(default), `put`, or `patch`.
Create Case URL:: Rest API URL to create case in third party system. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Create Case URL:: Rest API URL to create case in third party system. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
Create Case URL:: Rest API URL to create case in third-party system. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the `host.name` is added to the allowed hosts.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lcawl tagging you in this in case it should be host name, host name, or hostname.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i dont think this should be host.name, since we're not talking about ECS but instead a website domain name

@stephmilovic
Copy link
Contributor Author

@nastasha-solomon updated most of your requests and left comments where i was unsure

Define Webhook - Case Management connector properties:

[role="screenshot"]
image::management/connectors/images/cases-webhook-connector.gif[Webhook - Case Management connector]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image::management/connectors/images/cases-webhook-connector.gif[Webhook - Case Management connector]

IMO this would be simpler to maintain as a static image, like in the other connector pages. Ideally the UI is intuitive enough that it doesn't require this animation.

Test Webhook - Case Management action parameters:

[role="screenshot"]
image::management/connectors/images/cases-webhook-test.gif[Webhook - Case Management params test]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image::management/connectors/images/cases-webhook-test.gif[Webhook - Case Management params test]

Ditto re preference for static image that we can then automatically update and maintain.


[float]
[[cases-webhook-connector-full-example]]
== Full example with third-party system
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

== Full example with third-party system

IMO everything hereafter is more suited to a blog rather than the docs. These connector docs are intended as reference information (and will gradually be reduced even further as we move the information into the appropriate API reference pages). So an example like this (especially since it says the preconfigured Jira connector is the preferred choice) seems more like a learning exercise in a blog.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my tech lead requested we put an example here. if you want it in a blog, can we publish it at the same time this is published and link it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we have links to important blogs in the Machine Learning docs, so it is fine to do so here too once that information is published.

Copy link
Contributor

@lcawl lcawl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have commented out the example for now so that this PR can be merged

@kibanamachine
Copy link
Contributor

💚 All backports created successfully

Status Branch Result
8.4

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation and see the Github Action logs for details

kibanamachine added a commit to kibanamachine/kibana that referenced this pull request Aug 12, 2022
Mpdreamz pushed a commit to Mpdreamz/kibana that referenced this pull request Sep 6, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
auto-backport Deprecated - use backport:version if exact versions are needed release_note:skip Skip the PR/issue when compiling release notes Team:ResponseOps Label for the ResponseOps team (formerly the Cases and Alerting teams) Team: SecuritySolution Security Solutions Team working on SIEM, Endpoint, Timeline, Resolver, etc. Team:Threat Hunting:Explore v8.4.0 v8.5.0
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants