@cccsaurora/howler-ui 2.14.0-dev.263 → 2.14.0-dev.265

package/components/routes/help/TemplateDocumentation.tsx

@@ -0,0 +1,73 @@
+import { Card, CardContent, Stack } from '@mui/material';
+import PageCenter from '@cccsaurora/howler-ui/commons/components/pages/PageCenter';
+import Markdown from '@cccsaurora/howler-ui/components/elements/display/Markdown';
+import { HitLayout } from '@cccsaurora/howler-ui/components/elements/hit/HitLayout';
+import DefaultOutline from '@cccsaurora/howler-ui/components/elements/hit/outlines/DefaultOutline';
+import { useScrollRestoration } from '@cccsaurora/howler-ui/components/hooks/useScrollRestoration';
+import dayjs from 'dayjs';
+import type { FC } from 'react';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import TEMPLATES_EN from './markdown/en/templates.md';
+import TEMPLATES_FR from './markdown/fr/templates.md';
+
+const ALERTS = [
+  {
+    howler: { id: 'hit1', analytic: 'Cat Checker', detection: 'Listening for Meows' },
+    event: {
+      start: dayjs().subtract(4, 'hour').toString(),
+      end: dayjs().subtract(3, 'hour').toString(),
+      kind: 'Loud meow',
+      outcome: 'Food provided'
+    }
+  },
+  {
+    howler: { id: 'hit2', analytic: 'Cat Checker', detection: 'Looking for paw prints' },
+    event: {
+      start: dayjs().subtract(6, 'hour').toString(),
+      end: dayjs().subtract(5, 'hour').toString(),
+      provider: "The neighbour's cat (probably)",
+      reason: 'There was some fish we forgot to put away in the kitchen'
+    }
+  }
+];
+
+const TemplateDocumentation: FC = () => {
+  const { i18n } = useTranslation();
+  useScrollRestoration();
+
+  const [md1, md2] = useMemo(() => {
+    let markdown = i18n.language === 'en' ? TEMPLATES_EN : TEMPLATES_FR;
+
+    markdown = markdown.replace(/\$CURRENT_URL/g, window.location.origin);
+
+    ALERTS.forEach((alert, index) => {
+      markdown = markdown.replace(`$ALERT_${index + 1}`, JSON.stringify(alert, null, 2));
+    });
+
+    return markdown.split('\n===SPLIT===\n');
+  }, [i18n.language]);
+
+  return (
+    <PageCenter margin={4} width="100%" textAlign="left">
+      <Markdown md={md1} />
+      <Stack spacing={1}>
+        {ALERTS.map(alert => (
+          <Card key={alert.howler.id} variant="outlined">
+            <CardContent>
+              <DefaultOutline
+                hit={alert as any}
+                fields={Object.keys(alert).flatMap(key => Object.keys(alert[key]).map(key2 => [key, key2].join('.')))}
+                layout={HitLayout.NORMAL}
+                readonly
+              />
+            </CardContent>
+          </Card>
+        ))}
+      </Stack>
+      <Markdown md={md2} />
+    </PageCenter>
+  );
+};
+export default TemplateDocumentation;

package/components/routes/help/ViewDocumentation.tsx

@@ -0,0 +1,32 @@
+import { Search } from '@mui/icons-material';
+import PageCenter from '@cccsaurora/howler-ui/commons/components/pages/PageCenter';
+import Markdown from '@cccsaurora/howler-ui/components/elements/display/Markdown';
+import { useScrollRestoration } from '@cccsaurora/howler-ui/components/hooks/useScrollRestoration';
+import type { FC } from 'react';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import VIEWS_EN from './markdown/en/views.md';
+import VIEWS_FR from './markdown/fr/views.md';
+
+const ViewDocumentation: FC = () => {
+  const { i18n } = useTranslation();
+  useScrollRestoration();
+
+  const md = useMemo(
+    () => (i18n.language === 'en' ? VIEWS_EN : VIEWS_FR).replace(/\$CURRENT_URL/g, window.location.origin),
+    [i18n.language]
+  );
+
+  return (
+    <PageCenter margin={4} width="100%" textAlign="left">
+      <Markdown
+        md={md}
+        components={{
+          search: <Search fontSize="inherit" />
+        }}
+      />
+    </PageCenter>
+  );
+};
+export default ViewDocumentation;

package/components/routes/help/components/HelpTabs.tsx

@@ -0,0 +1,47 @@
+import { Tabs, useMediaQuery, useTheme } from '@mui/material';
+import type { FC, PropsWithChildren } from 'react';
+
+interface TabProps {
+  value: string;
+}
+
+const HelpTabs: FC<PropsWithChildren<TabProps>> = ({ children, value }) => {
+  const theme = useTheme();
+  const useHorizontal = useMediaQuery(theme.breakpoints.down(1700));
+
+  return (
+    <Tabs
+      value={value}
+      orientation={useHorizontal ? 'horizontal' : 'vertical'}
+      variant="scrollable"
+      scrollButtons="auto"
+      sx={[
+        {
+          position: 'sticky',
+          top: theme.spacing(8),
+          flexShrink: 0,
+          alignSelf: 'stretch',
+          backgroundColor: 'background.paper',
+          zIndex: 100,
+          '& a': { p: 1, minHeight: 'initial' }
+        },
+        useHorizontal
+          ? {
+              marginLeft: '-40px',
+              marginRight: '-40px'
+            }
+          : {
+              mr: 3,
+              minWidth: '225px',
+              '& a': {
+                alignItems: 'start'
+              }
+            }
+      ]}
+    >
+      {children}
+    </Tabs>
+  );
+};
+
+export default HelpTabs;

package/components/routes/help/markdown/en/actionIntroduction.md

@@ -0,0 +1,33 @@
+# Using Actions in Howler
+
+Actions are a feature in Howler that allow users to perform particular tasks on a large number of hits, through automating the execution of a task on each hit. There are currently `action_count` operations supported in howler:
+
+`action_list`
+
+All of these operations can be combined together into unique actions - that is, operations are essentially the building blocks of actions in Howler. Each operation can only appear once per action, and all operations are configured through one unified UI. In this document, we will walk through the steps necessary to run and save an action.
+
+## Configuring an Action
+
+In order to begin configuring your action, decide if this will be a one-off action or a saved action you want to run several times. If you want to run it once, use the `t(route.actions.change)` entry in the sidebar, while a saved action is best configured under the `t(route.actions.manager)` by pressing "`t(route.actions.create)`".
+
+The first step of any action will be to design a query on which you want this action to run. The search box at the top of the accepts any lucene query - the same format as searching for hits.
+
+`tui_phrase`
+
+Once you are satisfied with the hits that will be included in this query, you can begin adding operations. You can do so by selecting the operation you want to add from the dropdown:
+
+`operation_select`
+
+Once you've selected the operation you want to add, it will prompt you for a list of parameters you will need to fill out. Below is an example for adding a label.
+
+`operation_configuration`
+
+Once the operation validates successfully, you can repeat this process with the next operation. Once you've added all the operations you're interested in, you can execute or save the action using the button below the search bar. This will generate a report of the steps taken.
+
+`report`
+
+Occaisionally, actions will result in an error, either on validation or on execution. In these cases, an error alert will be shown, helping you solve the issue.
+
+## Automating an Action
+
+In order to automate an action, open any saved action. The options available to you for automation (`automation_options`) will show up as checkboxes. Checking the box will ensure this action will run then - no further work required.

package/components/routes/help/markdown/en/authentication.md

@@ -0,0 +1,261 @@
+<!-- docs/ingestion/authentication.md -->
+
+# Howler Authentication
+
+Howler's API supports a number of authentication approaches when accessing the API. This document will outline the
+different approaches, and explain how to use each of them.
+
+## Types of Authentication
+
+There are four methods of authentication one can use to connect to the howler API:
+
+1. Username and Password
+2. Username and API Key
+3. Username and app token (after login)
+4. OAuth Access Token
+
+We will outline the use case for each authentication type next.
+
+### Username/Password Authentication
+
+Username and password authentication is the simplest and least secure method of authentication. Unlikely to be enabled
+in a production environment, it allows users to easily connect to the Howler API and make changes as the given user,
+without having to worry about creating API keys or using an OAuth provider like Keycloak or Azure. Users can connect
+using username and password authentication in one of two ways:
+
+#### Direct Call to the Requisite Endpoint (Password)
+
+This is far and away the simplest method. Simply add a basic Authorization header to the HTTP request you want to
+make, and everything is taken care of:
+
+```bash
+echo -n "user:user" | base64 -w0
+# -> dXNlcjp1c2Vy
+```
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Basic dXNlcjp1c2Vy
+```
+
+#### Exchanging for an App Token (Password)
+
+This is a slightly more complex approach, but carries the benefit of not exposing the username and password on every
+request. You can leverage the `v1/auth/login` endpoint to exchange your username and password for an app token. The
+token works similarly to an OAuth access token - you provide it with each subsequent request, and it authenticates you
+until the token expires.
+
+```http
+POST $CURRENT_URL/api/v1/auth/login/
+Content-Type: application/json
+
+{
+  "user": "user",
+  "password": "user"
+}
+```
+
+Will return something like:
+
+```json
+{
+  "api_error_message": "",
+  "api_response": {
+    "app_token": "user:5791a142067745c3af51d6596da7da8f86357a9fa92ad78d1ce118ea7d89d34e",
+    "provider": null,
+    "refresh_token": null
+  },
+  "api_server_version": "0.0.0.dev0",
+  "api_status_code": 200
+}
+```
+
+Using this token in another API call:
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Bearer user:5791a142067745c3af51d6596da7da8f86357a9fa92ad78d1ce118ea7d89d34e
+```
+
+### Username/API Key Authentication
+
+The username and API Key authentication works largely the same as username/password from the perspective of the client.
+On the server side, however, API keys have several key advantages. Firstly, they can easily be revoked by the user.
+Secondly, their privileges can be limited, allowing only a subset of permissions.
+
+There are two methods of authentication, mirroring the username and password:
+
+#### Direct Call to the Requisite Endpoint (API Key)
+
+Simply add a basic Authorization header containing the username and API key to the HTTP request you want to make, and
+everything is taken care of:
+
+```bash
+# note the format is <username>:<apikeyname>:<secret>
+echo -n "user:devkey:user" | base64 -w0
+# -> dXNlcjpkZXZrZXk6dXNlcg==
+```
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Basic dXNlcjpkZXZrZXk6dXNlcg==
+```
+
+#### Exchanging for an App Token (API Key)
+
+You can also leverage the `v1/auth/login` endpoint to exchange your username and API key for an app token. The
+token works similarly to an OAuth access token - you provide it with each subsequent request, and it authenticates you
+until the token expires.
+
+```http
+POST $CURRENT_URL/api/v1/auth/login/
+Content-Type: application/json
+
+{
+  "user": "user",
+  "apikey": "devkey:user"
+}
+```
+
+Will return something like:
+
+```json
+{
+  "api_error_message": "",
+  "api_response": {
+    "app_token": "user:f220eb76ff8404abfece8c0c2f3368c7d89618c776bedcd3a506843dc4a952e4",
+    "provider": null,
+    "refresh_token": null
+  },
+  "api_server_version": "0.0.0.dev0",
+  "api_status_code": 200
+}
+```
+
+Using this token in another API call:
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Bearer user:f220eb76ff8404abfece8c0c2f3368c7d89618c776bedcd3a506843dc4a952e4
+```
+
+Note that when logging in using an api key, the permissions of the api key continue to apply. So if you try and access
+an endpoint that requires the "write" permission with an API key that only has read permission, this will cause a 403
+Forbidden error.
+
+### Access Token Authentication
+
+In addition to the authentication methods provided internally by Howler, you can also authenticate with an external
+OAuth provider like Azure or Keycloak. To do this, you must obtain an access token from one of these providers. In
+order to get an access token, there are generally two flows - On-Behalf-Of, or the user login flow (see [here](https://www.rfc-editor.org/rfc/rfc6749#section-4.1) for a rundown
+of that). In the case of Howler, the `v1/auth/login` endpoint is used for step D & E in the linked user login flow, and
+it returns the following:
+
+```json
+{
+  "api_response": {
+    "app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyIn0",
+    "provider": "keycloak",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWZyZXNoIn0"
+  }
+}
+```
+
+In this case, the `app_token` is the JSON Web Token the application uses as an access token. Similarly, the
+`refresh_token` is another JWT that is used to refresh the access token if needed. Finally, the `provider` field
+outlines which provider this access token corresponds to.
+
+Once you have that access token, you can simply pass it along in the Authorization header:
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyIn0
+```
+
+Howler will automatically detect this is a JWT, and treat it as such. If the token is valid, the user will be
+authenticated.
+
+In order to refresh an expired access token, you can use the following API call:
+
+```http
+POST $CURRENT_URL/api/v1/auth/login/
+Content-Type: application/json
+
+{
+  "oauth_provider": "keycloak",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWZyZXNoIn0"
+}
+```
+
+And you'll get something like this back:
+
+```json
+{
+  "api_response": {
+    "app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMiJ9",
+    "provider": "keycloak",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWZyZXNodG9rZW4yIn0"
+  }
+}
+```
+
+## Impersonation
+
+The final important bit of the authentication flow is the impersonation functionality. In order for a service account
+or other user to impersonate you (i.e. to create alerts on your behalf), Howler allows users to provide a second API key
+in order to authenticate as another user.
+
+Before you use another user's API key to authenticate as them, it's important that the API key you're using has been
+marked as valid for impersonation - check with the user that provided it. If it has, you can use it by, formating your
+request as follows:
+
+```bash
+# Your credentials
+echo -n "admin:devkey:admin" | base64 -w0
+# -> YWRtaW46ZGV2a2V5OmFkbWlu
+
+# Their credentials
+echo -n "user:impersonate_admin:user" | base64 -w0
+# -> dXNlcjppbXBlcnNvbmF0ZV9hZG1pbjp1c2Vy
+```
+
+```alert
+Any form of authentication can be used by the impersonator, but validated API keys are the only permitted
+authentication method for the person you're impersonating.
+```
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Basic YWRtaW46ZGV2a2V5OmFkbWlu
+X-Impersonating: Basic dXNlcjppbXBlcnNvbmF0ZV9hZG1pbjp1c2Vy
+```
+
+If set up correctly, the result will look like:
+
+```json
+{
+  "api_error_message": "",
+  "api_response": {
+    "avatar": null,
+    "classification": "TLP:W",
+    "email": "user@howler.cyber.gc.ca",
+    "groups": ["USERS"],
+    "is_active": true,
+    "is_admin": false,
+    "name": "User",
+    "roles": ["user"],
+    "username": "user"
+  },
+  "api_server_version": "0.0.0.dev0",
+  "api_status_code": 200
+}
+```
+
+Note that the server returned this as if you were `user`, NOT `admin`. It is clearly marked in the logs, however, that you are making the request:
+
+```log
+22/12/05 14:15:02 INFO howler.api.security | Authenticating user for path /api/v1/user/whoami/
+22/12/05 14:15:03 WARNING howler.api.security | admin is impersonating user
+22/12/05 14:15:03 INFO howler.api.security | Logged in as user from 127.0.0.1
+22/12/05 14:15:03 INFO howler.api | GET /api/v1/user/whoami/ - 200
+```

package/components/routes/help/markdown/en/bundles.md

@@ -0,0 +1,70 @@
+<!-- docs/ingestion/bundles.md -->
+
+# Howler Hit Bundles
+
+Hit bundles can be used to easily package together a large number of similar alerts, allowing analysts to easily triage them as a single incident. For example, consider a single computer that repeatedly makes a network call to `baddomain.ru` - while an alert may be generated for every instance of this computer hitting that domain, it makes sense for analysts to treat all these alerts as a single case.
+
+## Creating bundles through the Howler Client
+
+There are a couple of ways to create a bundle through the howler client:
+
+```python
+from howler_client import get_client
+
+howler = get_client("https://howler.dev.analysis.cyber.gc.ca")
+
+"""Creating a howler bundle and the hits at the same time"""
+howler.bundle.create(
+    # First argument is the bundle hit
+    {
+        "howler.analytic": "example-test",
+        "howler.score": 0
+    },
+    # Second argument is a hit or list of hits to include in the bundle
+    [
+        {
+            "howler.analytic": "example-test",
+            "howler.score": 0
+        },
+        {
+            "howler.analytic": "example-test",
+            "howler.score": 0
+        }
+    ]
+)
+
+"""Creating a howler bundle from existing hits"""
+howler.bundle.create(
+    {
+        "howler.analytic": "example-test",
+        "howler.score": 0,
+        "howler.hits": ["YcUsL8QsjmwwIdstieROk", "6s7MztwuSvz6tM0PgGJhvz"]
+    },
+    # Note: In future releases, you won't need to include this argument
+    []
+)
+
+
+"""Creating from a map"""
+bundle_hit = {
+    "score": 0,
+    "bundle": True
+}
+
+map = {
+    "score": ["howler.score"],
+    "bundle": ["howler.is_bundle"]
+}
+
+howler.bundle.create_from_map("example-test", bundle_hit, map, [{"score": 0}])
+```
+
+## Viewing bundles on the Howler UI
+
+In order to view created bundles on the Howler UI, you can use the query `howler.is_bundle:true`. This will provide a list of created bundles you can look through.
+
+Clicking on a bundle will open up a slightly different search UI to normal. In this case, we automatically filter the search results to include only hits that are included in the bundle. To make this obvious, the header representing the bundle will appear above the search bar.
+
+You can continue to filter through hits using the same queries as usual, and view them as usual. When triaging a bundle, assessing it will apply this assessment to all hits in the bundle, **except those that have already been triaged**. That is, if the bundle is open, all open hits will be assessed when you assess it.
+
+Bundles also have a **Summary** tab not available for regular hits. This summary tab will aid you in aggregating data about all the hits in the bundle. Simply open the tab and click "Create Summary". Note that this may take some time, as a large number of queries are being run to aggregate the data.