@cccsaurora/howler-ui 2.19.0-cases.863 → 2.19.0-dev.1023

package/components/routes/dossiers/Dossiers.js

@@ -2,6 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { Topic } from '@mui/icons-material';
 import { Typography } from '@mui/material';
 import api from '@cccsaurora/howler-ui/api';
+import { ModalContext } from '@cccsaurora/howler-ui/components/app/providers/ModalProvider';
+import SearchResponseProvider, { SearchResponseContext } from '@cccsaurora/howler-ui/components/app/providers/SearchResponseProvider';
 import { TuiListProvider } from '@cccsaurora/howler-ui/components/elements/addons/lists';
 import { TuiListMethodContext } from '@cccsaurora/howler-ui/components/elements/addons/lists/TuiListProvider';
 import ItemManager from '@cccsaurora/howler-ui/components/elements/display/ItemManager';
@@ -18,12 +20,13 @@ const DossiersBase = () => {
     const navigate = useNavigate();
     const { dispatchApi } = useMyApi();
     const { showSuccessMessage } = useMySnackbar();
+    const { withConfirmDeleteModal } = useContext(ModalContext);
     const [searchParams, setSearchParams] = useSearchParams();
     const { load } = useContext(TuiListMethodContext);
     const pageCount = useMyLocalStorageItem(StorageKey.PAGE_COUNT, 25)[0];
+    const { response, request, remove, getSearchRequestData } = useContext(SearchResponseContext);
     const [phrase, setPhrase] = useState('');
     const [offset, setOffset] = useState(parseInt(searchParams.get('offset')) || 0);
-    const [response, setResponse] = useState(null);
     const [hasError, setHasError] = useState(false);
     const [loading, setLoading] = useState(false);
     const onSearch = useCallback(async () => {
@@ -40,11 +43,11 @@ const DossiersBase = () => {
             // Check for the actual search query
             const query = phrase ? `*:*${phrase}*` : '*:*';
             // Ensure the overview should be visible and/or matches the type we are filtering for
-            setResponse(await dispatchApi(api.search.dossier.post({
+            await request(api.search.dossier.post, {
                 query,
                 rows: pageCount,
                 offset
-            })));
+            });
         }
         catch (e) {
             setHasError(true);
@@ -52,7 +55,7 @@ const DossiersBase = () => {
         finally {
             setLoading(false);
         }
-    }, [phrase, setSearchParams, searchParams, dispatchApi, pageCount, offset]);
+    }, [phrase, setSearchParams, searchParams, request, pageCount, offset]);
     // Load the items into list when response changes.
     // This hook should only trigger when the 'response' changes.
     useEffect(() => {
@@ -68,24 +71,27 @@ const DossiersBase = () => {
     }, [response, load]);
     const onPageChange = useCallback((_offset) => {
         if (_offset !== offset) {
-            searchParams.set('offset', _offset.toString());
+            const modifiedRequest = getSearchRequestData({ offset: _offset });
+            searchParams.set('offset', modifiedRequest.offset.toString());
             setSearchParams(searchParams, { replace: true });
-            setOffset(_offset);
+            setOffset(modifiedRequest.offset);
         }
-    }, [offset, searchParams, setSearchParams]);
-    const onDelete = useCallback(async (e, id) => {
+    }, [offset, searchParams, setSearchParams, getSearchRequestData]);
+    const onDelete = useCallback((e, id) => {
         e.preventDefault();
         e.stopPropagation();
-        try {
-            await dispatchApi(api.dossier.del(id), { throwError: false, showError: true });
-            await onSearch();
-            showSuccessMessage(t('route.dossiers.manager.delete.success'));
-        }
-        catch (_err) {
-            // eslint-disable-next-line no-console
-            console.warn(_err);
-        }
-    }, [dispatchApi, onSearch, showSuccessMessage, t]);
+        withConfirmDeleteModal(async () => {
+            try {
+                await dispatchApi(api.dossier.del(id), { throwError: true, showError: true });
+                remove(id);
+                showSuccessMessage(t('route.dossiers.manager.delete.success'));
+            }
+            catch (_err) {
+                // eslint-disable-next-line no-console
+                console.warn(_err);
+            }
+        });
+    }, [dispatchApi, remove, withConfirmDeleteModal, showSuccessMessage, t]);
     useEffect(() => {
         onSearch();
         if (!searchParams.has('offset')) {
@@ -111,6 +117,6 @@ const DossiersBase = () => {
     return (_jsx(ItemManager, { onSearch: onSearch, onPageChange: onPageChange, phrase: phrase, setPhrase: setPhrase, hasError: hasError, searching: loading, aboveSearch: _jsx(Typography, { sx: theme => ({ fontStyle: 'italic', color: theme.palette.text.disabled, mb: 0.5 }), variant: "body2", children: t('route.dossiers.search.prompt') }), renderer: ({ item }, classRenderer) => renderer(item.item, classRenderer()), response: response, onSelect: (item) => navigate(`/dossiers/${item.id}/edit`), onCreate: () => navigate('/dossiers/create'), createPrompt: "route.dossiers.create", searchPrompt: "route.dossiers.manager.search", createIcon: _jsx(Topic, { sx: { mr: 1 } }) }));
 };
 const Dossiers = () => {
-    return (_jsx(TuiListProvider, { children: _jsx(DossiersBase, {}) }));
+    return (_jsx(TuiListProvider, { children: _jsx(SearchResponseProvider, { idField: "dossier_id", children: _jsx(DossiersBase, {}) }) }));
 };
 export default Dossiers;

package/components/routes/help/ApiDocumentation.js

@@ -49,7 +49,7 @@ const ApiDocumentation = () => {
                                             .replace(/(\S+)\s+=>\s+(.+)/g, '\n`$1`: $2\n')
                                             .replace(/(Data Block:\n)([\s\S]+)(Result Example:)/, (__, p1, p2, p3) => `${p1}\`\`\`\n${p2.trim()}\n\`\`\`\n${p3}`)
                                             .replace(/(Result Example:\n)([\s\S]+)$/, (__, p1, p2) => `${p1}\`\`\`\n${p2.trim()}\n\`\`\``) }));
-                                    return (_jsxs(Fragment, { children: [_jsxs(TableRow, { style: { marginBottom: '1rem' }, sx: [isLg && { '& > td': { borderBottom: 0 } }], children: [_jsx(TableCell, { children: _jsxs(Stack, { direction: "column", spacing: 1, alignItems: "start", children: [_jsx(Typography, { children: endpoint.name }), _jsx("code", { children: endpoint.path }), _jsxs(Stack, { direction: "row", spacing: 1, children: [endpoint.complete ? (_jsx(Chip, { label: "Stable", color: "success" })) : (_jsx(Chip, { label: "Unstable", color: "error" })), endpoint.protected ? (_jsx(Chip, { label: "Protected", color: "warning" })) : (_jsx(Chip, { label: "Unprotected" }))] }), _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.methods.map(m => (_jsx(Chip, { size: "small", label: m }, m))) }), endpoint.ui_only && _jsx(Chip, { label: "UI Only" })] }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_type.map(type => (_jsx(Chip, { size: "small", label: type, color: user.roles?.includes(type) ? 'success' : 'default' }, type))) }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_priv.map((p) => (_jsx(Chip, { size: "small", label: t(APIKEY_LABELS[p]) }, p))) }) }), !isLg && _jsx(TableCell, { children: documentationCell })] }), isLg && (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: 3, sx: { '& pre': { whiteSpace: 'pre-wrap' } }, children: documentationCell }) }))] }, endpoint.id));
+                                    return (_jsxs(Fragment, { children: [_jsxs(TableRow, { style: { marginBottom: '1rem' }, sx: [isLg && { '& > td': { borderBottom: 0 } }], children: [_jsx(TableCell, { children: _jsxs(Stack, { direction: "column", spacing: 1, alignItems: "start", children: [_jsx(Typography, { children: endpoint.name }), _jsx("code", { children: endpoint.path }), _jsxs(Stack, { direction: "row", spacing: 1, children: [endpoint.complete ? (_jsx(Chip, { size: "small", label: "Stable", color: "success" })) : (_jsx(Chip, { size: "small", label: "Unstable", color: "error" })), endpoint.protected ? (_jsx(Chip, { size: "small", label: "Protected", color: "warning" })) : (_jsx(Chip, { size: "small", label: "Unprotected" }))] }), _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.methods.map(m => (_jsx(Chip, { size: "small", label: m }, m))) }), endpoint.ui_only && _jsx(Chip, { size: "small", label: "UI Only" })] }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_type.map(type => (_jsx(Chip, { size: "small", label: type, color: user.roles?.includes(type) ? 'success' : 'default' }, type))) }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_priv.map((p) => (_jsx(Chip, { size: "small", label: t(APIKEY_LABELS[p]) }, p))) }) }), !isLg && _jsx(TableCell, { children: documentationCell })] }), isLg && (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: 3, sx: { '& pre': { whiteSpace: 'pre-wrap' } }, children: documentationCell }) }))] }, endpoint.id));
                                 }) })] }) })] }) }));
 };
 export default ApiDocumentation;

package/components/routes/help/BundleDocumentation.d.ts

@@ -0,0 +1,3 @@
+import type { FC } from 'react';
+declare const BundleDocumentation: FC;
+export default BundleDocumentation;

package/components/routes/help/BundleDocumentation.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Markdown from '@cccsaurora/howler-ui/components/elements/display/Markdown';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import BUNDLES_EN from './markdown/en/bundles.md';
+import BUNDLES_FR from './markdown/fr/bundles.md';
+const BundleDocumentation = () => {
+    const { i18n } = useTranslation();
+    const md = useMemo(() => (i18n.language === 'en' ? BUNDLES_EN : BUNDLES_FR), [i18n.language]);
+    return _jsx(Markdown, { md: md });
+};
+export default BundleDocumentation;

package/components/routes/help/HitBannerDocumentation.js

@@ -9,7 +9,6 @@ import { useTranslation } from 'react-i18next';
 const HitBannerDocumentation = () => {
     const { t } = useTranslation();
     const dummyHit = useMemo(() => ({
-        __index: 'hit',
         timestamp: '2023-02-11T15:10:31.585826Z',
         howler: {
             id: 'howler.id',

package/components/routes/help/HitDocumentation.js

@@ -5,6 +5,7 @@ import { useScrollRestoration } from '@cccsaurora/howler-ui/components/hooks/use
 import { useCallback, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSearchParams } from 'react-router-dom';
+import BundleDocumentation from './BundleDocumentation';
 import HelpTabs from './components/HelpTabs';
 import HitBannerDocumentation from './HitBannerDocumentation';
 import HitLabelsDocumentation from './HitLabelsDocumentation';
@@ -22,7 +23,8 @@ const HitDocumentation = () => {
         searchParams.set('tab', _tab);
         setSearchParams(new URLSearchParams(searchParams));
     }, [searchParams, setSearchParams]);
-    return (_jsx(PageCenter, { margin: 4, width: "100%", maxWidth: "1750px", textAlign: "left", children: _jsxs(Stack, { sx: { flexDirection: useHorizontal ? 'column' : 'row', '& h1': { mt: 0 } }, children: [_jsxs(HelpTabs, { value: tab, children: [_jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.schema.title') }), value: "schema", onClick: () => onChange('schema') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.banner.title') }), value: "header", onClick: () => onChange('header') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.links.title') }), value: "links", onClick: () => onChange('links') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.labels.title') }), value: "labels", onClick: () => onChange('labels') })] }), _jsx(Box, { children: {
+    return (_jsx(PageCenter, { margin: 4, width: "100%", maxWidth: "1750px", textAlign: "left", children: _jsxs(Stack, { sx: { flexDirection: useHorizontal ? 'column' : 'row', '& h1': { mt: 0 } }, children: [_jsxs(HelpTabs, { value: tab, children: [_jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.schema.title') }), value: "schema", onClick: () => onChange('schema') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.banner.title') }), value: "header", onClick: () => onChange('header') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.bundle.title') }), value: "bundle", onClick: () => onChange('bundle') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.links.title') }), value: "links", onClick: () => onChange('links') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.labels.title') }), value: "labels", onClick: () => onChange('labels') })] }), _jsx(Box, { children: {
+                        bundle: () => _jsx(BundleDocumentation, {}),
                         header: () => _jsx(HitBannerDocumentation, {}),
                         links: () => _jsx(HitLinksDocumentation, {}),
                         labels: () => _jsx(HitLabelsDocumentation, {}),

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

@@ -0,0 +1 @@
+export default "<!-- docs/ingestion/bundles.md -->\n\n# Howler Hit Bundles\n\nHit 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.\n\n## Creating bundles through the Howler Client\n\nThere are a couple of ways to create a bundle through the howler client:\n\n```python\nfrom howler_client import get_client\n\nhowler = get_client(\"https://howler.dev.analysis.cyber.gc.ca\")\n\n\"\"\"Creating a howler bundle and the hits at the same time\"\"\"\nhowler.bundle.create(\n    # First argument is the bundle hit\n    {\n        \"howler.analytic\": \"example-test\",\n        \"howler.score\": 0\n    },\n    # Second argument is a hit or list of hits to include in the bundle\n    [\n        {\n            \"howler.analytic\": \"example-test\",\n            \"howler.score\": 0\n        },\n        {\n            \"howler.analytic\": \"example-test\",\n            \"howler.score\": 0\n        }\n    ]\n)\n\n\"\"\"Creating a howler bundle from existing hits\"\"\"\nhowler.bundle.create(\n    {\n        \"howler.analytic\": \"example-test\",\n        \"howler.score\": 0,\n        \"howler.hits\": [\"YcUsL8QsjmwwIdstieROk\", \"6s7MztwuSvz6tM0PgGJhvz\"]\n    },\n    # Note: In future releases, you won't need to include this argument\n    []\n)\n\n\n\"\"\"Creating from a map\"\"\"\nbundle_hit = {\n    \"score\": 0,\n    \"bundle\": True\n}\n\nmap = {\n    \"score\": [\"howler.score\"],\n    \"bundle\": [\"howler.is_bundle\"]\n}\n\nhowler.bundle.create_from_map(\"example-test\", bundle_hit, map, [{\"score\": 0}])\n```\n\n## Viewing bundles on the Howler UI\n\nIn 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.\n\nClicking 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.\n\nYou 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.\n\nBundles 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.\n"

package/components/routes/help/markdown/en/client.md.js

@@ -1 +1 @@
-export default "# Howler Client Documentation\n\nThis documentation will outline how to interact with the howler API using the howler client in both Java and python development environments. We will outline the basic process of creating a new hit in each environment as well as searching howler for hits matching your query.\n\n## Getting started\n\n### Installation\n\nIn order to use the howler client, you need to list it as a dependency in your project.\n\n#### **Python**\n\nSimply install through pip:\n\n```bash\npip install howler-client\n```\n\nYou can also add it to your requirements.txt, or whatever dependency management system you use.\n\n### Authentication\n\nAs outlined in the [Authentication Documentation](/help/auth), there's a number of ways users can choose to authenticate. In order to interface with the howler client, however, the suggested flow is to use an API key. So before we start, let's generate a key.\n\n1. Open the Howler UI you'd like to interface with.\n2. Log in, then click your profile in the top right.\n3. Under user menu, click Settings.\n4. Under User Security, press the (+) icon on the API Keys row.\n5. Name your key, and give it the requisite permissions.\n6. Press Create, and copy the supplied string somewhere safe. **You will not see this string again.**\n\nThis API Key will be supplied to your code later on.\n\n## Python Client\n\nIn order to connect with howler using the python client, there is a fairly simple process to follow:\n\n```python\nfrom howler_client import get_client\n\nUSERNAME = 'user' # Obtain this from the user settings page of the Howler UI\nAPIKEY = 'apikey_name:apikey_data'\n\napikey = (USERNAME, APIKEY)\n\nhowler = get_client(\"$CURRENT_URL\", apikey=apikey)\n```\n\n```alert\nYou can skip generating an API Key and providing it if you're executing this code within HOGWARTS (i.e., on jupyterhub or airflow). OBO will handle authentication for you!\n```\n\nThat's it! You can now use the `howler` object to interact with the server. So what does that actually look like?\n\n### Creating hits in Python\n\nFor the python client, you can create hits using either the `howler.hit.create` or `howler.hit.create_from_map` functions.\n\n#### `create`\n\nThis function takes in a single argument - either a single hit, or a list of them, conforming to the [Howler Schema](/help/hit?tab=schema). Here is a simple example:\n\n```python\n# Some bogus data in the Howler Schema format\nexample_hit = {\n  \"howler\": {\n    \"analytic\": \"example\",\n    \"score\": 10.0\n  },\n  \"event\": {\n    \"reason\": \"Example hit\"\n  }\n}\n\nhowler.hit.create(example_hit)\n```\n\nYou can also ingest data in a flat format:\n\n```python\nexample_hit = {\n  \"howler.analytic\": \"example\",\n  \"howler.score\": 10.0,\n  \"event.reason\": \"Example hit\"\n}\n\nhowler.hit.create(example_hit)\n```\n\n#### `create_from_map`\n\nThis function takes in three arguments:\n\n- `tool name`: The name of the analytic creating the hit\n- `map`: A mapping between the raw data you have and the howler schema\n  - The format is a dictionary where the keys are the flattened path of the raw data, and the values are a list of flattened paths for Howler's fields where the data will be copied into.\n- `documents`: The raw data you want to add to howler\n\nHere is a simple example:\n\n```python\n# The mapping from our data to howler's schema\nhwl_map = {\n  \"file.sha256\": [\"file.hash.sha256\", \"howler.hash\"],\n  \"file.name\": [\"file.name\"],\n  \"src_ip\": [\"source.ip\", \"related.ip\"],\n  \"dest_ip\": [\"destination.ip\", \"related.ip\"],\n  \"time.created\": [\"event.start\"],\n}\n\n# Some bogus data in a custom format we want to add to howler\nexample_hit = {\n  \"src_ip\": \"0.0.0.0\",\n  \"dest_ip\": \"8.8.8.8\",\n  \"file\": {\n    \"name\": \"hello.exe\",\n    \"sha256\": sha256(str(\"hello.exe\").encode()).hexdigest()\n  },\n  \"time\": {\n    \"created\": datetime.now().isoformat()\n  },\n}\n\n# Note that the third argument is of type list!\nhowler.hit.create_from_map(\"example_ingestor\", hwl_map, [example_hit])\n```\n\n### Querying Hits\n\nQuerying hits using the howler python client is done using the `howler.search.hit` function. It has a number of required and optional arguments:\n\n- Required:\n  - `query`: lucene query (string)\n- Optional:\n  - `filters`: Additional lucene queries used to filter the data (list of strings)\n  - `fl`: List of fields to return (comma separated string of fields)\n  - `offset`: Offset at which the query items should start (integer)\n  - `rows`: Number of records to return (integer)\n  - `sort`: Field used for sorting with direction (string: ex. 'id desc')\n  - `timeout`: Max amount of milliseconds the query will run (integer)\n  - `use_archive`: Also query the archive\n  - `track_total_hits`: Number of hits to track (default: 10k)\n\nHere are some example queries:\n\n```python\n# Search for all hits created by assemblyline, show the first 50, and return only their ids\nhowler.search.hit(\"howler.analytic:assemblyline\", fl=\"howler.id\", rows=50)\n\n# Search for all resolved hits created in the last five days, returning their id and the analytic that created them. Show only ten, offset by 40\nhowler.search.hit(\"howler.status:resolved\", filters=['event.created:[now-5d TO now]'] fl=\"howler.id,howler.analytic\", rows=10, offset=40)\n\n# Search for all hits, timeout if the query takes more than 100ms\nhowler.search.hit(\"howler.id:*\", track_total_hits=100000000, timeout=100, use_archive=True)\n```\n\n### Updating Hits\n\nIn order to update hits, there are a number of supported functions:\n\n- `howler.hit.update(...)`\n- `howler.hit.update_by_query(...)`\n- `howler.hit.overwrite(...)`\n\n#### `update()`\n\nIf you want to update a hit in a transactional way, you can use the following code:\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.update(hit_to_update[\"howler\"][\"id\"], [(UPDATE_SET, \"howler.score\", hit_to_update[\"howler\"][\"score\"] + 100)])\n```\n\nThe following operations can be run to update a hit.\n\n**List Operations:**\n\n- `UPDATE_APPEND`: Used to append a value to a given list\n- `UPDATE_APPEND_IF_MISSING`: Used to append a value to a given list if the value isn't already in the list\n- `UPDATE_REMOVE`: Will remove a given value from a list\n\n**Numeric Operations:**\n\n- `UPDATE_DEC`: Decrement a numeric value by the specified amount\n- `UPDATE_INC`: Increment a numeric value by the specified amount\n- `UPDATE_MAX`: Will set a numeric value to the maximum of the existing value and the specified value\n- `UPDATE_MIN`: Will set a numeric value to the minimum of the existing value and the specified value\n\n**Multipurpose Operations:**\n\n- `UPDATE_SET`: Set a field's value to the given value\n- `UPDATE_DELETE`: Will delete a given field's value\n\n#### `update_by_query()`\n\nThis function allows you to update a large number of hits by a query:\n\n```python\nclient.hit.update_by_query(f'howler.analytic:\"Example Alert\"', [(UPDATE_INC, \"howler.score\", 100)])\n```\n\nThe same operations as in `update()` can be used.\n\n### `overwrite()`\n\nThis function allows you to directly overwrite a hit with a partial hit object. This is the most easy to use, but loses some of the validation and additional processing of the update functions.\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.overwrite(hit_to_update[\"howler\"][\"id\"], {\"source.ip\": \"127.0.0.1\", \"destination.ip\": \"8.8.8.8\"})\n```\n"
+export default "# Howler Client Documentation\n\nThis documentation will outline how to interact with the howler API using the howler client in both Java and python development environments. We will outline the basic process of creating a new hit in each environment as well as searching howler for hits matching your query.\n\n## Getting started\n\n### Installation\n\nIn order to use the howler client, you need to list it as a dependency in your project.\n\n#### **Python**\n\nSimply install through pip:\n\n```bash\npip install howler-client\n```\n\nYou can also add it to your requirements.txt, or whatever dependency management system you use.\n\n### Authentication\n\nAs outlined in the [Authentication Documentation](/help/auth), there's a number of ways users can choose to authenticate. In order to interface with the howler client, however, the suggested flow is to use an API key. So before we start, let's generate a key.\n\n1. Open the Howler UI you'd like to interface with.\n2. Log in, then click your profile in the top right.\n3. Under user menu, click Settings.\n4. Under User Security, press the (+) icon on the API Keys row.\n5. Name your key, and give it the requisite permissions.\n6. Press Create, and copy the supplied string somewhere safe. **You will not see this string again.**\n\nThis API Key will be supplied to your code later on.\n\n## Python Client\n\nIn order to connect with howler using the python client, there is a fairly simple process to follow:\n\n```python\nfrom howler_client import get_client\n\nUSERNAME = 'user' # Obtain this from the user settings page of the Howler UI\nAPIKEY = 'apikey_name:apikey_data'\n\napikey = (USERNAME, APIKEY)\n\nhowler = get_client(\"$CURRENT_URL\", apikey=apikey)\n```\n\n```alert\nYou can skip generating an API Key and providing it if you're executing this code within HOGWARTS (i.e., on jupyterhub or airflow). OBO will handle authentication for you!\n```\n\nThat's it! You can now use the `howler` object to interact with the server. So what does that actually look like?\n\n### Creating hits in Python\n\nFor the python client, you can create hits using either the `howler.hit.create` or `howler.hit.create_from_map` functions.\n\n#### `create`\n\nThis function takes in a single argument - either a single hit, or a list of them, conforming to the [Howler Schema](/help/hit?tab=schema). Here is a simple example:\n\n```python\n# Some bogus data in the Howler Schema format\nexample_hit = {\n  \"howler\": {\n    \"analytic\": \"example\",\n    \"score\": 10.0\n  },\n  \"event\": {\n    \"reason\": \"Example hit\"\n  }\n}\n\nhowler.hit.create(example_hit)\n```\n\nYou can also ingest data in a flat format:\n\n```python\nexample_hit = {\n  \"howler.analytic\": \"example\",\n  \"howler.score\": 10.0,\n  \"event.reason\": \"Example hit\"\n}\n\nhowler.hit.create(example_hit)\n```\n\n#### `create_from_map`\n\nThis function takes in three arguments:\n\n- `tool name`: The name of the analytic creating the hit\n- `map`: A mapping between the raw data you have and the howler schema\n  - The format is a dictionary where the keys are the flattened path of the raw data, and the values are a list of flattened paths for Howler's fields where the data will be copied into.\n- `documents`: The raw data you want to add to howler\n\nHere is a simple example:\n\n```python\n# The mapping from our data to howler's schema\nhwl_map = {\n  \"file.sha256\": [\"file.hash.sha256\", \"howler.hash\"],\n  \"file.name\": [\"file.name\"],\n  \"src_ip\": [\"source.ip\", \"related.ip\"],\n  \"dest_ip\": [\"destination.ip\", \"related.ip\"],\n  \"time.created\": [\"event.start\"],\n}\n\n# Some bogus data in a custom format we want to add to howler\nexample_hit = {\n  \"src_ip\": \"0.0.0.0\",\n  \"dest_ip\": \"8.8.8.8\",\n  \"file\": {\n    \"name\": \"hello.exe\",\n    \"sha256\": sha256(str(\"hello.exe\").encode()).hexdigest()\n  },\n  \"time\": {\n    \"created\": datetime.now().isoformat()\n  },\n}\n\n# Note that the third argument is of type list!\nhowler.hit.create_from_map(\"example_ingestor\", hwl_map, [example_hit])\n```\n\n### Querying Hits\n\nQuerying hits using the howler python client is done using the `howler.search.hit` function. It has a number of required and optional arguments:\n\n- Required:\n  - `query`: lucene query (string)\n- Optional:\n  - `filters`: Additional lucene queries used to filter the data (list of strings)\n  - `fl`: List of fields to return (comma separated string of fields)\n  - `offset`: Offset at which the query items should start (integer)\n  - `rows`: Number of records to return (integer)\n  - `sort`: Field used for sorting with direction (string: ex. 'id desc')\n  - `timeout`: Max amount of milliseconds the query will run (integer)\n  - `track_total_hits`: Number of hits to track (default: 10k)\n\nHere are some example queries:\n\n```python\n# Search for all hits created by assemblyline, show the first 50, and return only their ids\nhowler.search.hit(\"howler.analytic:assemblyline\", fl=\"howler.id\", rows=50)\n\n# Search for all resolved hits created in the last five days, returning their id and the analytic that created them. Show only ten, offset by 40\nhowler.search.hit(\"howler.status:resolved\", filters=['event.created:[now-5d TO now]'] fl=\"howler.id,howler.analytic\", rows=10, offset=40)\n\n# Search for all hits, timeout if the query takes more than 100ms\nhowler.search.hit(\"howler.id:*\", track_total_hits=100000000, timeout=100)\n```\n\n### Updating Hits\n\nIn order to update hits, there are a number of supported functions:\n\n- `howler.hit.update(...)`\n- `howler.hit.update_by_query(...)`\n- `howler.hit.overwrite(...)`\n\n#### `update()`\n\nIf you want to update a hit in a transactional way, you can use the following code:\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.update(hit_to_update[\"howler\"][\"id\"], [(UPDATE_SET, \"howler.score\", hit_to_update[\"howler\"][\"score\"] + 100)])\n```\n\nThe following operations can be run to update a hit.\n\n**List Operations:**\n\n- `UPDATE_APPEND`: Used to append a value to a given list\n- `UPDATE_APPEND_IF_MISSING`: Used to append a value to a given list if the value isn't already in the list\n- `UPDATE_REMOVE`: Will remove a given value from a list\n\n**Numeric Operations:**\n\n- `UPDATE_DEC`: Decrement a numeric value by the specified amount\n- `UPDATE_INC`: Increment a numeric value by the specified amount\n- `UPDATE_MAX`: Will set a numeric value to the maximum of the existing value and the specified value\n- `UPDATE_MIN`: Will set a numeric value to the minimum of the existing value and the specified value\n\n**Multipurpose Operations:**\n\n- `UPDATE_SET`: Set a field's value to the given value\n- `UPDATE_DELETE`: Will delete a given field's value\n\n#### `update_by_query()`\n\nThis function allows you to update a large number of hits by a query:\n\n```python\nclient.hit.update_by_query(f'howler.analytic:\"Example Alert\"', [(UPDATE_INC, \"howler.score\", 100)])\n```\n\nThe same operations as in `update()` can be used.\n\n### `overwrite()`\n\nThis function allows you to directly overwrite a hit with a partial hit object. This is the most easy to use, but loses some of the validation and additional processing of the update functions.\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.overwrite(hit_to_update[\"howler\"][\"id\"], {\"source.ip\": \"127.0.0.1\", \"destination.ip\": \"8.8.8.8\"})\n```\n"

package/components/routes/help/markdown/fr/bundles.md.js

@@ -0,0 +1 @@
+export default "<!-- docs/ingestion/bundles.fr.md -->\n\n# Les groupes des hits Howler\n\nLes groupes des hits peuvent \u00eatre utilis\u00e9s pour regrouper facilement un grand nombre d'alertes similaires, ce qui permet aux analystes de les traiter comme un seul incident. Prenons l'exemple d'un ordinateur qui effectue \u00e0 plusieurs reprises un appel r\u00e9seau vers `baddomain.ru` - bien qu'une alerte puisse \u00eatre g\u00e9n\u00e9r\u00e9e pour chaque cas o\u00f9 cet ordinateur acc\u00e8de \u00e0 ce domaine, il est logique que les analystes traitent toutes ces alertes comme un seul et m\u00eame cas.\n\n## Cr\u00e9ation de groupes via le client Howler\n\nIl y a plusieurs fa\u00e7ons de cr\u00e9er un groupe via le client Howler:\n\n```python\nfrom howler_client import get_client\n\nhowler = get_client(\"https://howler.dev.analysis.cyber.gc.ca\")\n\n\"\"\"Cr\u00e9ation simultan\u00e9e d'un groupe howler et de hits\"\"\"\nhowler.bundle.create(\n    # Le premier argument est le hit de l'offre group\u00e9e\n    {\n        \"howler.analytic\": \"example-test\",\n        \"howler.score\": 0\n    },\n    # Le deuxi\u00e8me argument est un hit ou une liste de hits \u00e0 inclure dans l'offre group\u00e9e.\n    [\n        {\n            \"howler.analytic\": \"example-test\",\n            \"howler.score\": 0\n        },\n        {\n            \"howler.analytic\": \"example-test\",\n            \"howler.score\": 0\n        }\n    ]\n)\n\n\"\"\"Cr\u00e9ation d'un groupe howler \u00e0 partir de hits existants\"\"\"\nhowler.bundle.create(\n    {\n        \"howler.analytic\": \"example-test\",\n        \"howler.score\": 0,\n        \"howler.hits\": [\"YcUsL8QsjmwwIdstieROk\", \"6s7MztwuSvz6tM0PgGJhvz\"]\n    },\n    # Noter: Dans les prochaines versions, vous n'aurez plus besoin d'inclure cet argument.\n    []\n)\n\n\n\"\"\"Cr\u00e9ation \u00e0 partir d'une carte\"\"\"\nbundle_hit = {\n    \"score\": 0,\n    \"bundle\": True\n}\n\nmap = {\n    \"score\": [\"howler.score\"],\n    \"bundle\": [\"howler.is_bundle\"]\n}\n\nhowler.bundle.create_from_map(\"example-test\", bundle_hit, map, [{\"score\": 0}])\n```\n\n## Visualiser les groupes sur l'interface utilisateur de Howler\n\nAfin de visualiser les groupes cr\u00e9\u00e9s sur l'interface utilisateur de Howler, vous pouvez utiliser la requ\u00eate `howler.is_bundle:true`. Cela fournira une liste de groupes cr\u00e9\u00e9s que vous pourrez consulter.\n\nEn cliquant sur un groupe, vous ouvrirez une interface de recherche l\u00e9g\u00e8rement diff\u00e9rente de l'interface normale. Dans ce cas, nous filtrons automatiquement les r\u00e9sultats de la recherche pour n'inclure que les r\u00e9sultats inclus dans le groupe. Pour que cela soit \u00e9vident, l'en-t\u00eate repr\u00e9sentant le groupe appara\u00eet au-dessus de la barre de recherche.\n\nVous pouvez continuer \u00e0 filtrer les r\u00e9sultats en utilisant les m\u00eames requ\u00eates que d'habitude et \u00e0 les visualiser comme d'habitude. Lors du triage d'un groupe, son \u00e9valuation s'appliquera \u00e0 tous les hits du groupe, **sauf ceux qui ont d\u00e9j\u00e0 \u00e9t\u00e9 tri\u00e9s**. En d'autres termes, si le groupe est ouvert, tous les hits ouverts seront \u00e9valu\u00e9s lorsque vous l'\u00e9valuerez.\n\nLes groupes disposent \u00e9galement d'un onglet **R\u00e9sum\u00e9** qui n'est pas disponible pour les hits ordinaires. Cet onglet vous aidera \u00e0 regrouper les donn\u00e9es relatives \u00e0 tous les r\u00e9sultats du groupe. Il suffit d'ouvrir l'onglet et de cliquer sur \"Cr\u00e9er un sommaire\". Notez que cette op\u00e9ration peut prendre un certain temps, car un grand nombre de requ\u00eates sont ex\u00e9cut\u00e9es pour agr\u00e9ger les donn\u00e9es.\n"

package/components/routes/help/markdown/fr/client.md.js

@@ -1 +1 @@
-export default "# Documentation du client Howler\n\nCette documentation explique comment interagir avec l'API howler en utilisant le client howler dans les environnements de d\u00e9veloppement Java et Python. Nous d\u00e9crirons le processus de base de la cr\u00e9ation d'un nouveau hit dans chaque environnement ainsi que la recherche dans howler des hits correspondant \u00e0 votre requ\u00eate.\n\n## Mise en route\n\n### Installation\n\nAfin d'utiliser le client howler, vous devez le lister comme une d\u00e9pendance dans votre projet.\n\n#### **Python**\n\nIl suffit de l'installer \u00e0 l'aide de pip:\n\n```bash\npip install howler-client\n```\n\nVous pouvez \u00e9galement l'ajouter \u00e0 votre requirements.txt, ou \u00e0 tout autre syst\u00e8me de gestion des d\u00e9pendances que vous utilisez.\n\n### Authentification\n\nComme indiqu\u00e9 dans la [Documentation sur l'authentification](/help/auth), les utilisateurs peuvent s'authentifier de diff\u00e9rentes mani\u00e8res. Pour interfacer avec le client howler, cependant, le flux sugg\u00e9r\u00e9 est d'utiliser une cl\u00e9 API. Avant de commencer, g\u00e9n\u00e9rons une cl\u00e9.\n\n1. Ouvrez l'interface utilisateur Howler avec laquelle vous souhaitez vous interfacer.\n2. Connectez-vous, puis cliquez sur votre profil en haut \u00e0 droite.\n3. Dans le menu utilisateur, cliquez sur Param\u00e8tres.\n4. Sous S\u00e9curit\u00e9 de l'utilisateur, appuyez sur l'ic\u00f4ne (+) sur la ligne Cl\u00e9s API.\n5. Nommez votre cl\u00e9 et donnez-lui les autorisations n\u00e9cessaires.\n6. Appuyez sur Create (Cr\u00e9er) et copiez la cha\u00eene fournie dans un endroit s\u00fbr. \\*\\*Vous ne reverrez plus cette cha\u00eene.\n\nCette cl\u00e9 API sera fournie \u00e0 votre code par la suite.\n\n## Client Python\n\nPour se connecter \u00e0 howler en utilisant le client python, il y a un processus assez simple \u00e0 suivre:\n\n```python\nfrom howler_client import get_client\n\nUSERNAME = 'user' # Obtenez-le \u00e0 partir de la page des param\u00e8tres de l'utilisateur de l'interface utilisateur de Howler.\nAPIKEY = 'apikey_name:apikey_data'\n\napikey = (USERNAME, APIKEY)\n\nhowler = get_client(\"$CURRENT_URL\", apikey=apikey)\n```\n\nVoil\u00e0, c'est fait ! Vous pouvez maintenant utiliser l'objet `howler` pour interagir avec le serveur. A quoi cela ressemble-t-il en r\u00e9alit\u00e9?\n\n### Cr\u00e9er des hits en Python\n\nPour le client python, vous pouvez cr\u00e9er des hits en utilisant les fonctions `howler.hit.create` ou `howler.hit.create_from_map`.\n\n#### `create`\n\nCette fonction prend un seul argument - soit un hit unique, soit une liste de hits, conforme au [Howler Schema] (/help/hit?tab=schema). Voici un exemple simple :\n\n```python\n# Quelques donn\u00e9es bidons au format Howler Schema\nexemple_hit = {\n  \"howler\" : {\n    \"analytic\" : \"exemple\",\n    \"score\" : 10.0\n  },\n  \"event\" : {\n    \"reason\" : \"Exemple hit\"\n  }\n}\n\nhowler.hit.create(example_hit)\n```\n\nVous pouvez \u00e9galement ing\u00e9rer des donn\u00e9es dans un format plat :\n\n```python\nexample_hit = {\n  \"howler.analytic\": \"example\",\n  \"howler.score\": 10.0,\n  \"event.reason\": \"Example hit\"\n}\n\nhowler.hit.create(example_hit)\n```\n\n#### `create_from_map`\n\nThis function takes in three arguments:\n\n- `tool name`: Le nom de l'outil d'analyse qui cr\u00e9e le hit\n- `map`: Une correspondance entre les donn\u00e9es brutes que vous avez et le sch\u00e9ma howler\n  - Le format est un dictionnaire o\u00f9 les cl\u00e9s sont le chemin aplati des donn\u00e9es brutes, et les valeurs sont une liste de chemins aplatis pour les champs de Howler dans lesquels les donn\u00e9es seront copi\u00e9es.\n- `documents`: Les donn\u00e9es brutes que vous voulez ajouter \u00e0 Howler.\n\nVoici un exemple simple:\n\n```python\n# La correspondance entre nos donn\u00e9es et le sch\u00e9ma de Howler\nhwl_map = {\n  \"file.sha256\": [\"file.hash.sha256\", \"howler.hash\"],\n  \"file.name\": [\"file.name\"],\n  \"src_ip\": [\"source.ip\", \"related.ip\"],\n  \"dest_ip\": [\"destination.ip\", \"related.ip\"],\n  \"time.created\": [\"event.start\"],\n}\n\n# Quelques fausses donn\u00e9es dans un format personnalis\u00e9 que nous voulons ajouter \u00e0 howler\nexample_hit = {\n  \"src_ip\": \"0.0.0.0\",\n  \"dest_ip\": \"8.8.8.8\",\n  \"file\": {\n    \"name\": \"hello.exe\",\n    \"sha256\": sha256(str(\"hello.exe\").encode()).hexdigest()\n  },\n  \"time\": {\n    \"created\": datetime.now().isoformat()\n  },\n}\n\n# Notez que le troisi\u00e8me argument est de type liste!\nhowler.hit.create_from_map(\"example_ingestor\", hwl_map, [example_hit])\n```\n\n### Interroger les hits en Python\n\nL'interrogation des hits avec le client python howler se fait en utilisant la fonction `howler.search.hit`. Elle poss\u00e8de un certain nombre d'arguments obligatoires et optionnels:\n\n- Obligatoire:\n  - `query`: requ\u00eate lucene (cha\u00eene)\n- Facultatif: `filters`: requ\u00eate lucene (cha\u00eene):\n  - `filters`: Requ\u00eates lucene additionnelles utilis\u00e9es pour filtrer les donn\u00e9es (liste de cha\u00eenes)\n  - `fl`: Liste des champs \u00e0 retourner (cha\u00eene de champs s\u00e9par\u00e9s par des virgules)\n  - `offset`: Offset auquel les \u00e9l\u00e9ments de la requ\u00eate doivent commencer (entier)\n  - `rows`: Nombre d'enregistrements \u00e0 retourner (entier)\n  - `sort`: Champ utilis\u00e9 pour le tri avec direction (cha\u00eene: ex. 'id desc')\n  - `timeout`: Nombre maximum de millisecondes d'ex\u00e9cution de la requ\u00eate (entier)\n  - `use_archive`: Interroge \u00e9galement l'archive\n  - `track_total_hits`: Nombre de hits \u00e0 suivre (par d\u00e9faut: 10k)\n\nVoici quelques exemples de requ\u00eates:\n\n```python\n# Rechercher tous les hits cr\u00e9\u00e9s par assemblyline, afficher les 50 premiers et ne renvoyer que leurs identifiants.\nhowler.search.hit(\"howler.analytic:assemblyline\", fl=\"howler.id\", rows=50)\n\n# Recherche de toutes les occurrences r\u00e9solues cr\u00e9\u00e9es au cours des cinq derniers jours, avec indication de leur identifiant et de l'analyste qui les a cr\u00e9\u00e9es. N'en afficher que dix, d\u00e9cal\u00e9s de 40\nhowler.search.hit(\"howler.status:resolved\", filters=['event.created:[now-5d TO now]'] fl=\"howler.id,howler.analytic\", rows=10, offset=40)\n\n# Recherche de tous les r\u00e9sultats, d\u00e9lai d'attente si la requ\u00eate prend plus de 100 ms\nhowler.search.hit(\"howler.id:*\", track_total_hits=100000000, timeout=100, use_archive=True)\n```\n\n### Mise \u00e0 jour des r\u00e9sultats\n\nAfin de mettre \u00e0 jour les hits, il existe un certain nombre de fonctions support\u00e9es :\n\n- `howler.hit.update(...)`\n- `howler.hit.update_by_query(...)`\n- `howler.hit.overwrite(...)`\n\n#### `update()`\n\nSi vous souhaitez mettre \u00e0 jour un hit de mani\u00e8re transactionnelle, vous pouvez utiliser le code suivant:\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.update(hit_to_update[\"howler\"][\"id\"], [(UPDATE_SET, \"howler.score\", hit_to_update[\"howler\"][\"score\"] + 100)])\n```\n\nLes op\u00e9rations suivantes peuvent \u00eatre ex\u00e9cut\u00e9es pour mettre \u00e0 jour un r\u00e9sultat.\n\n**Op\u00e9rations de liste:**\n\n- `UPDATE_APPEND` : Utilis\u00e9 pour ajouter une valeur \u00e0 une liste donn\u00e9e\n- `UPDATE_APPEND_IF_MISSING` : Utilis\u00e9 pour ajouter une valeur \u00e0 une liste donn\u00e9e si la valeur n'est pas d\u00e9j\u00e0 dans la liste.\n- `UPDATE_REMOVE` : Supprime une valeur donn\u00e9e d'une liste\n\n**Op\u00e9rations num\u00e9riques:**\n\n- `UPDATE_DEC` : Diminue une valeur num\u00e9rique de la quantit\u00e9 sp\u00e9cifi\u00e9e.\n- `UPDATE_INC` : Incr\u00e9mente une valeur num\u00e9rique de la quantit\u00e9 sp\u00e9cifi\u00e9e.\n- `UPDATE_MAX` : Fixe une valeur num\u00e9rique au maximum de la valeur existante et de la valeur sp\u00e9cifi\u00e9e.\n- `UPDATE_MIN` : Fixe une valeur num\u00e9rique au minimum de la valeur existante et de la valeur sp\u00e9cifi\u00e9e.\n\n**Op\u00e9rations polyvalentes:**\n\n- `UPDATE_SET` : Fixe la valeur d'un champ \u00e0 la valeur donn\u00e9e.\n- `UPDATE_DELETE` : Supprime la valeur d'un champ donn\u00e9\n\n#### `update_by_query()`\n\nCette fonction vous permet de mettre \u00e0 jour un grand nombre d'occurrences \u00e0 l'aide d'une requ\u00eate :\n\n```python\nclient.hit.update_by_query(f'howler.analytic : \"Exemple d\\'analytic\"', [(UPDATE_INC, \"howler.score\", 100)])\n```\n\nLes m\u00eames op\u00e9rations que dans `update()` peuvent \u00eatre utilis\u00e9es.\n\n### `overwrite()`\n\nCette fonction vous permet d'\u00e9craser directement un hit avec un objet hit partiel. C'est la plus facile \u00e0 utiliser, mais elle perd une partie de la validation et du traitement suppl\u00e9mentaire des fonctions de mise \u00e0 jour.\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.overwrite(hit_to_update[\"howler\"][\"id\"], {\"source.ip\" : \"127.0.0.1\", \u201cdestination.ip\u201d : \"8.8.8.8\"})\n```\n"
+export default "# Documentation du client Howler\n\nCette documentation explique comment interagir avec l'API howler en utilisant le client howler dans les environnements de d\u00e9veloppement Java et Python. Nous d\u00e9crirons le processus de base de la cr\u00e9ation d'un nouveau hit dans chaque environnement ainsi que la recherche dans howler des hits correspondant \u00e0 votre requ\u00eate.\n\n## Mise en route\n\n### Installation\n\nAfin d'utiliser le client howler, vous devez le lister comme une d\u00e9pendance dans votre projet.\n\n#### **Python**\n\nIl suffit de l'installer \u00e0 l'aide de pip:\n\n```bash\npip install howler-client\n```\n\nVous pouvez \u00e9galement l'ajouter \u00e0 votre requirements.txt, ou \u00e0 tout autre syst\u00e8me de gestion des d\u00e9pendances que vous utilisez.\n\n### Authentification\n\nComme indiqu\u00e9 dans la [Documentation sur l'authentification](/help/auth), les utilisateurs peuvent s'authentifier de diff\u00e9rentes mani\u00e8res. Pour interfacer avec le client howler, cependant, le flux sugg\u00e9r\u00e9 est d'utiliser une cl\u00e9 API. Avant de commencer, g\u00e9n\u00e9rons une cl\u00e9.\n\n1. Ouvrez l'interface utilisateur Howler avec laquelle vous souhaitez vous interfacer.\n2. Connectez-vous, puis cliquez sur votre profil en haut \u00e0 droite.\n3. Dans le menu utilisateur, cliquez sur Param\u00e8tres.\n4. Sous S\u00e9curit\u00e9 de l'utilisateur, appuyez sur l'ic\u00f4ne (+) sur la ligne Cl\u00e9s API.\n5. Nommez votre cl\u00e9 et donnez-lui les autorisations n\u00e9cessaires.\n6. Appuyez sur Create (Cr\u00e9er) et copiez la cha\u00eene fournie dans un endroit s\u00fbr. \\*\\*Vous ne reverrez plus cette cha\u00eene.\n\nCette cl\u00e9 API sera fournie \u00e0 votre code par la suite.\n\n## Client Python\n\nPour se connecter \u00e0 howler en utilisant le client python, il y a un processus assez simple \u00e0 suivre:\n\n```python\nfrom howler_client import get_client\n\nUSERNAME = 'user' # Obtenez-le \u00e0 partir de la page des param\u00e8tres de l'utilisateur de l'interface utilisateur de Howler.\nAPIKEY = 'apikey_name:apikey_data'\n\napikey = (USERNAME, APIKEY)\n\nhowler = get_client(\"$CURRENT_URL\", apikey=apikey)\n```\n\nVoil\u00e0, c'est fait ! Vous pouvez maintenant utiliser l'objet `howler` pour interagir avec le serveur. A quoi cela ressemble-t-il en r\u00e9alit\u00e9?\n\n### Cr\u00e9er des hits en Python\n\nPour le client python, vous pouvez cr\u00e9er des hits en utilisant les fonctions `howler.hit.create` ou `howler.hit.create_from_map`.\n\n#### `create`\n\nCette fonction prend un seul argument - soit un hit unique, soit une liste de hits, conforme au [Howler Schema] (/help/hit?tab=schema). Voici un exemple simple :\n\n```python\n# Quelques donn\u00e9es bidons au format Howler Schema\nexemple_hit = {\n  \"howler\" : {\n    \"analytic\" : \"exemple\",\n    \"score\" : 10.0\n  },\n  \"event\" : {\n    \"reason\" : \"Exemple hit\"\n  }\n}\n\nhowler.hit.create(example_hit)\n```\n\nVous pouvez \u00e9galement ing\u00e9rer des donn\u00e9es dans un format plat :\n\n```python\nexample_hit = {\n  \"howler.analytic\": \"example\",\n  \"howler.score\": 10.0,\n  \"event.reason\": \"Example hit\"\n}\n\nhowler.hit.create(example_hit)\n```\n\n#### `create_from_map`\n\nThis function takes in three arguments:\n\n- `tool name`: Le nom de l'outil d'analyse qui cr\u00e9e le hit\n- `map`: Une correspondance entre les donn\u00e9es brutes que vous avez et le sch\u00e9ma howler\n  - Le format est un dictionnaire o\u00f9 les cl\u00e9s sont le chemin aplati des donn\u00e9es brutes, et les valeurs sont une liste de chemins aplatis pour les champs de Howler dans lesquels les donn\u00e9es seront copi\u00e9es.\n- `documents`: Les donn\u00e9es brutes que vous voulez ajouter \u00e0 Howler.\n\nVoici un exemple simple:\n\n```python\n# La correspondance entre nos donn\u00e9es et le sch\u00e9ma de Howler\nhwl_map = {\n  \"file.sha256\": [\"file.hash.sha256\", \"howler.hash\"],\n  \"file.name\": [\"file.name\"],\n  \"src_ip\": [\"source.ip\", \"related.ip\"],\n  \"dest_ip\": [\"destination.ip\", \"related.ip\"],\n  \"time.created\": [\"event.start\"],\n}\n\n# Quelques fausses donn\u00e9es dans un format personnalis\u00e9 que nous voulons ajouter \u00e0 howler\nexample_hit = {\n  \"src_ip\": \"0.0.0.0\",\n  \"dest_ip\": \"8.8.8.8\",\n  \"file\": {\n    \"name\": \"hello.exe\",\n    \"sha256\": sha256(str(\"hello.exe\").encode()).hexdigest()\n  },\n  \"time\": {\n    \"created\": datetime.now().isoformat()\n  },\n}\n\n# Notez que le troisi\u00e8me argument est de type liste!\nhowler.hit.create_from_map(\"example_ingestor\", hwl_map, [example_hit])\n```\n\n### Interroger les hits en Python\n\nL'interrogation des hits avec le client python howler se fait en utilisant la fonction `howler.search.hit`. Elle poss\u00e8de un certain nombre d'arguments obligatoires et optionnels:\n\n- Obligatoire:\n  - `query`: requ\u00eate lucene (cha\u00eene)\n- Facultatif: `filters`: requ\u00eate lucene (cha\u00eene):\n  - `filters`: Requ\u00eates lucene additionnelles utilis\u00e9es pour filtrer les donn\u00e9es (liste de cha\u00eenes)\n  - `fl`: Liste des champs \u00e0 retourner (cha\u00eene de champs s\u00e9par\u00e9s par des virgules)\n  - `offset`: Offset auquel les \u00e9l\u00e9ments de la requ\u00eate doivent commencer (entier)\n  - `rows`: Nombre d'enregistrements \u00e0 retourner (entier)\n  - `sort`: Champ utilis\u00e9 pour le tri avec direction (cha\u00eene: ex. 'id desc')\n  - `timeout`: Nombre maximum de millisecondes d'ex\u00e9cution de la requ\u00eate (entier)\n  - `track_total_hits`: Nombre de hits \u00e0 suivre (par d\u00e9faut: 10k)\n\nVoici quelques exemples de requ\u00eates:\n\n```python\n# Rechercher tous les hits cr\u00e9\u00e9s par assemblyline, afficher les 50 premiers et ne renvoyer que leurs identifiants.\nhowler.search.hit(\"howler.analytic:assemblyline\", fl=\"howler.id\", rows=50)\n\n# Recherche de toutes les occurrences r\u00e9solues cr\u00e9\u00e9es au cours des cinq derniers jours, avec indication de leur identifiant et de l'analyste qui les a cr\u00e9\u00e9es. N'en afficher que dix, d\u00e9cal\u00e9s de 40\nhowler.search.hit(\"howler.status:resolved\", filters=['event.created:[now-5d TO now]'] fl=\"howler.id,howler.analytic\", rows=10, offset=40)\n\n# Recherche de tous les r\u00e9sultats, d\u00e9lai d'attente si la requ\u00eate prend plus de 100 ms\nhowler.search.hit(\"howler.id:*\", track_total_hits=100000000, timeout=100)\n```\n\n### Mise \u00e0 jour des r\u00e9sultats\n\nAfin de mettre \u00e0 jour les hits, il existe un certain nombre de fonctions support\u00e9es :\n\n- `howler.hit.update(...)`\n- `howler.hit.update_by_query(...)`\n- `howler.hit.overwrite(...)`\n\n#### `update()`\n\nSi vous souhaitez mettre \u00e0 jour un hit de mani\u00e8re transactionnelle, vous pouvez utiliser le code suivant:\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.update(hit_to_update[\"howler\"][\"id\"], [(UPDATE_SET, \"howler.score\", hit_to_update[\"howler\"][\"score\"] + 100)])\n```\n\nLes op\u00e9rations suivantes peuvent \u00eatre ex\u00e9cut\u00e9es pour mettre \u00e0 jour un r\u00e9sultat.\n\n**Op\u00e9rations de liste:**\n\n- `UPDATE_APPEND` : Utilis\u00e9 pour ajouter une valeur \u00e0 une liste donn\u00e9e\n- `UPDATE_APPEND_IF_MISSING` : Utilis\u00e9 pour ajouter une valeur \u00e0 une liste donn\u00e9e si la valeur n'est pas d\u00e9j\u00e0 dans la liste.\n- `UPDATE_REMOVE` : Supprime une valeur donn\u00e9e d'une liste\n\n**Op\u00e9rations num\u00e9riques:**\n\n- `UPDATE_DEC` : Diminue une valeur num\u00e9rique de la quantit\u00e9 sp\u00e9cifi\u00e9e.\n- `UPDATE_INC` : Incr\u00e9mente une valeur num\u00e9rique de la quantit\u00e9 sp\u00e9cifi\u00e9e.\n- `UPDATE_MAX` : Fixe une valeur num\u00e9rique au maximum de la valeur existante et de la valeur sp\u00e9cifi\u00e9e.\n- `UPDATE_MIN` : Fixe une valeur num\u00e9rique au minimum de la valeur existante et de la valeur sp\u00e9cifi\u00e9e.\n\n**Op\u00e9rations polyvalentes:**\n\n- `UPDATE_SET` : Fixe la valeur d'un champ \u00e0 la valeur donn\u00e9e.\n- `UPDATE_DELETE` : Supprime la valeur d'un champ donn\u00e9\n\n#### `update_by_query()`\n\nCette fonction vous permet de mettre \u00e0 jour un grand nombre d'occurrences \u00e0 l'aide d'une requ\u00eate :\n\n```python\nclient.hit.update_by_query(f'howler.analytic : \"Exemple d\\'analytic\"', [(UPDATE_INC, \"howler.score\", 100)])\n```\n\nLes m\u00eames op\u00e9rations que dans `update()` peuvent \u00eatre utilis\u00e9es.\n\n### `overwrite()`\n\nCette fonction vous permet d'\u00e9craser directement un hit avec un objet hit partiel. C'est la plus facile \u00e0 utiliser, mais elle perd une partie de la validation et du traitement suppl\u00e9mentaire des fonctions de mise \u00e0 jour.\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.overwrite(hit_to_update[\"howler\"][\"id\"], {\"source.ip\" : \"127.0.0.1\", \u201cdestination.ip\u201d : \"8.8.8.8\"})\n```\n"

package/components/routes/hits/search/BundleParentMenu.d.ts

@@ -0,0 +1,6 @@
+import type { Hit } from '@cccsaurora/howler-ui/models/entities/generated/Hit';
+import type { FC } from 'react';
+declare const BundleParentMenu: FC<{
+    bundle: Hit;
+}>;
+export default BundleParentMenu;

package/components/routes/hits/search/BundleParentMenu.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { AccountTree } from '@mui/icons-material';
+import { IconButton, Paper, Popover, Skeleton, Stack, Tooltip } from '@mui/material';
+import api from '@cccsaurora/howler-ui/api';
+import HowlerCard from '@cccsaurora/howler-ui/components/elements/display/HowlerCard';
+import HitBanner from '@cccsaurora/howler-ui/components/elements/hit/HitBanner';
+import { HitLayout } from '@cccsaurora/howler-ui/components/elements/hit/HitLayout';
+import { useCallback, useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useNavigate } from 'react-router-dom';
+const BundleParentMenu = ({ bundle }) => {
+    const { t } = useTranslation();
+    const navigate = useNavigate();
+    const [parentAnchor, setParentAnchor] = useState(null);
+    const [parentHits, setParentHits] = useState([]);
+    const onSelect = useCallback((bundleId) => {
+        navigate(`/bundles/${bundleId}?span=date.range.all&query=howler.id%3A*`);
+        setParentAnchor(null);
+    }, [navigate]);
+    useEffect(() => {
+        if (!parentAnchor) {
+            return;
+        }
+        api.search.hit
+            .post({ query: `howler.id:(${bundle.howler.bundles.join(' OR ')})` })
+            .then(response => setParentHits(response.items));
+    }, [bundle.howler.bundles, parentAnchor]);
+    return (_jsxs(_Fragment, { children: [_jsx(Tooltip, { title: t('hit.bundle.parents.show'), children: _jsx(IconButton, { size: "small", onClick: event => setParentAnchor(event.currentTarget), children: _jsx(AccountTree, { fontSize: "small" }) }) }), _jsx(Popover, { open: !!parentAnchor, anchorEl: parentAnchor, anchorOrigin: { vertical: 'top', horizontal: 'left' }, transformOrigin: { horizontal: 'right', vertical: 'top' }, onClose: () => setParentAnchor(null), children: _jsx(Paper, { sx: { p: 1, minWidth: '750px' }, children: _jsx(Stack, { spacing: 1, children: parentHits.length < 1
+                            ? bundle.howler.bundles.map(id => _jsx(Skeleton, { variant: "rounded", height: "100px" }, id))
+                            : parentHits.map(parent => (_jsx(HowlerCard, { sx: { p: 1, cursor: 'pointer' }, onClick: () => onSelect(parent.howler.id), children: _jsx(HitBanner, { hit: parent, layout: HitLayout.DENSE }) }, parent.howler.id))) }) }) })] }));
+};
+export default BundleParentMenu;

package/components/routes/hits/search/BundleScroller.d.ts

@@ -0,0 +1,2 @@
+import type { FC, PropsWithChildren } from 'react';
+export declare const BundleScroller: FC<PropsWithChildren>;

package/components/routes/hits/search/BundleScroller.js

@@ -0,0 +1,6 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useScrollRestoration } from '@cccsaurora/howler-ui/components/hooks/useScrollRestoration';
+export const BundleScroller = ({ children }) => {
+    useScrollRestoration('hitscrollbar');
+    return _jsx(_Fragment, { children: children });
+};

package/components/routes/hits/search/{RecordBrowser.js → HitBrowser.js}

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronLeft, Close, ManageSearch } from '@mui/icons-material';
 import { Box, Card, Checkbox, Collapse, Drawer, Fab, IconButton, Stack, Tooltip, Typography, useMediaQuery, useTheme } from '@mui/material';
+import { HitContext } from '@cccsaurora/howler-ui/components/app/providers/HitProvider';
+import HitSearchProvider, { HitSearchContext } from '@cccsaurora/howler-ui/components/app/providers/HitSearchProvider';
 import ParameterProvider, { ParameterContext } from '@cccsaurora/howler-ui/components/app/providers/ParameterProvider';
-import { RecordContext } from '@cccsaurora/howler-ui/components/app/providers/RecordProvider';
-import RecordSearchProvider, { RecordSearchContext } from '@cccsaurora/howler-ui/components/app/providers/RecordSearchProvider';
 import { ViewContext } from '@cccsaurora/howler-ui/components/app/providers/ViewProvider';
 import FlexOne from '@cccsaurora/howler-ui/components/elements/addons/layout/FlexOne';
 import FlexPort from '@cccsaurora/howler-ui/components/elements/addons/layout/FlexPort';
@@ -32,14 +32,14 @@ const HitBrowser = () => {
     const setQuery = useContextSelector(ParameterContext, ctx => ctx.setQuery);
     const setOffset = useContextSelector(ParameterContext, ctx => ctx.setOffset);
     const selectedViews = useContextSelector(ParameterContext, ctx => ctx.views);
-    const selectedHits = useContextSelector(RecordContext, ctx => ctx.selectedRecords);
-    const addHitToSelection = useContextSelector(RecordContext, ctx => ctx.addRecordToSelection);
-    const removeHitFromSelection = useContextSelector(RecordContext, ctx => ctx.removeRecordFromSelection);
-    const clearSelectedHits = useContextSelector(RecordContext, ctx => ctx.clearSelectedRecords);
+    const selectedHits = useContextSelector(HitContext, ctx => ctx.selectedHits);
+    const addHitToSelection = useContextSelector(HitContext, ctx => ctx.addHitToSelection);
+    const removeHitFromSelection = useContextSelector(HitContext, ctx => ctx.removeHitFromSelection);
+    const clearSelectedHits = useContextSelector(HitContext, ctx => ctx.clearSelectedHits);
     const searchPaneWidth = useMyLocalStorageItem(StorageKey.SEARCH_PANE_WIDTH, null)[0];
     const forceDrawer = useMyLocalStorageItem(StorageKey.FORCE_DRAWER, false)[0];
-    const displayType = useContextSelector(RecordSearchContext, ctx => ctx.displayType);
-    const response = useContextSelector(RecordSearchContext, ctx => ctx.response);
+    const displayType = useContextSelector(HitSearchContext, ctx => ctx.displayType);
+    const response = useContextSelector(HitSearchContext, ctx => ctx.response);
     const location = useLocation();
     const routeParams = useParams();
     const [show, setShow] = useState(!!selected);
@@ -128,6 +128,6 @@ const HitBrowser = () => {
                 }, children: _jsx(ChevronLeft, { sx: { transition: 'rotate 250ms', rotate: show ? '180deg' : '0deg' } }) }))] }));
 };
 const HitBrowserProvider = () => {
-    return (_jsx(ParameterProvider, { children: _jsx(RecordSearchProvider, { children: _jsx(HitBrowser, {}) }) }));
+    return (_jsx(ParameterProvider, { children: _jsx(HitSearchProvider, { children: _jsx(HitBrowser, {}) }) }));
 };
 export default HitBrowserProvider;

package/components/{elements/record/RecordContextMenu.d.ts → routes/hits/search/HitContextMenu.d.ts}

@@ -3,7 +3,7 @@ import React from 'react';
 /**
  * Props for the HitContextMenu component
  */
-interface RecordContextMenuProps {
+interface HitContextMenuProps {
     /**
      * Function to extract the hit ID from a mouse event
      */
@@ -18,5 +18,5 @@ interface RecordContextMenuProps {
  * Provides quick access to common hit actions including assessment, voting,
  * transitions, and exclusion filters based on template fields.
  */
-declare const RecordContextMenu: FC<PropsWithChildren<RecordContextMenuProps>>;
-export default RecordContextMenu;
+declare const HitContextMenu: FC<PropsWithChildren<HitContextMenuProps>>;
+export default HitContextMenu;