@cccsaurora/howler-ui 2.18.0-dev.841 → 2.19.0-cases.1040

package/components/routes/cases/modals/ResolveModal.test.js

@@ -85,6 +85,9 @@ const createWrapper = (records = {}) => {
 const clickCheckbox = (checkbox) => {
     fireEvent.click(checkbox.parentElement);
 };
+const getHitCheckboxes = () => screen
+    .getAllByRole('checkbox')
+    .filter(checkbox => checkbox.getAttribute('aria-label') !== i18n.t('modal.cases.resolve.allow_unresolved.aria_label'));
 /** Fills in assessment and rationale so the confirm button becomes enabled. */
 const fillForm = async (user, assessment = 'legitimate', rationale = 'Test rationale') => {
     const rationaleInput = screen.getByPlaceholderText(i18n.t('modal.rationale.label'));
@@ -204,7 +207,7 @@ describe('ResolveModal', () => {
                 wrapper: createWrapper({ 'hit-1': HIT_1, 'hit-2': HIT_2 })
             });
             await waitFor(() => {
-                expect(screen.getAllByRole('checkbox')).toHaveLength(2);
+                expect(getHitCheckboxes()).toHaveLength(2);
             });
         });
         it('does not show a checkbox for resolved hits', async () => {
@@ -213,7 +216,7 @@ describe('ResolveModal', () => {
             });
             await waitFor(() => {
                 // only the single unresolved hit gets a checkbox
-                expect(screen.getAllByRole('checkbox')).toHaveLength(1);
+                expect(getHitCheckboxes()).toHaveLength(1);
             });
         });
         it('calls loadRecords with the API search results', async () => {
@@ -236,7 +239,9 @@ describe('ResolveModal', () => {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
             // Wait for the hit to load (checkbox appears) but don't select it
-            await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
             await fillForm(user);
             // No hit selected → selectedHitIds.size === 0 → button still disabled
             expect(screen.getByRole('button', { name: i18n.t('confirm') })).toBeDisabled();
@@ -245,7 +250,10 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            const [checkbox] = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            const [checkbox] = getHitCheckboxes();
             clickCheckbox(checkbox);
             await waitFor(() => expect(checkbox).toBeChecked());
             const rationaleInput = screen.getByPlaceholderText(i18n.t('modal.rationale.label'));
@@ -257,7 +265,10 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            const [checkbox] = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            const [checkbox] = getHitCheckboxes();
             clickCheckbox(checkbox);
             await waitFor(() => expect(checkbox).toBeChecked());
             // fill only assessment, no rationale
@@ -271,12 +282,29 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            const [checkbox] = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            const [checkbox] = getHitCheckboxes();
             clickCheckbox(checkbox);
             await waitFor(() => expect(checkbox).toBeChecked());
             await fillForm(user);
             expect(screen.getByRole('button', { name: i18n.t('confirm') })).toBeEnabled();
         });
+        it('is enabled when unresolved override is selected with no hits selected', async () => {
+            render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
+                wrapper: createWrapper({ 'hit-1': HIT_1 })
+            });
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            expect(screen.getByRole('button', { name: i18n.t('confirm') })).toBeDisabled();
+            const unresolvedOverride = screen.getByRole('checkbox', {
+                name: i18n.t('modal.cases.resolve.allow_unresolved.aria_label')
+            });
+            await user.click(unresolvedOverride);
+            expect(screen.getByRole('button', { name: i18n.t('confirm') })).toBeEnabled();
+        });
     });
     // -------------------------------------------------------------------------
     // Checkbox / selection toggling
@@ -286,7 +314,10 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            const [checkbox] = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            const [checkbox] = getHitCheckboxes();
             expect(checkbox).not.toBeChecked();
             clickCheckbox(checkbox);
             await waitFor(() => expect(checkbox).toBeChecked());
@@ -295,7 +326,10 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            const [checkbox] = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            const [checkbox] = getHitCheckboxes();
             clickCheckbox(checkbox);
             await waitFor(() => expect(checkbox).toBeChecked());
             clickCheckbox(checkbox);
@@ -305,7 +339,10 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1', 'hit-2']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1, 'hit-2': HIT_2 })
             });
-            const checkboxes = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(2);
+            });
+            const checkboxes = getHitCheckboxes();
             expect(checkboxes).toHaveLength(2);
             clickCheckbox(checkboxes[0]);
             await waitFor(() => {
@@ -322,7 +359,10 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            const [checkbox] = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            const [checkbox] = getHitCheckboxes();
             clickCheckbox(checkbox);
             await waitFor(() => expect(checkbox).toBeChecked());
             await fillForm(user, 'legitimate', 'My rationale');
@@ -335,7 +375,10 @@ describe('ResolveModal', () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            const [checkbox] = await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            const [checkbox] = getHitCheckboxes();
             clickCheckbox(checkbox);
             await waitFor(() => expect(checkbox).toBeChecked());
             await fillForm(user);
@@ -356,39 +399,56 @@ describe('ResolveModal', () => {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
             // Wait for loading to finish so no unexpected state transitions happen mid-click
-            await screen.findAllByRole('checkbox');
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
             await user.click(screen.getByRole('button', { name: i18n.t('cancel') }));
             expect(mockClose).toHaveBeenCalledTimes(1);
         });
     });
     // -------------------------------------------------------------------------
-    // Auto-resolve when all hits are already resolved
+    // Case resolution behavior
     // -------------------------------------------------------------------------
-    describe('auto-resolve', () => {
-        it('calls updateCase, onConfirm, and close when no unresolved hits remain after loading', async () => {
-            // All hits in the case are already resolved
+    describe('case resolution behavior', () => {
+        it('does NOT auto-resolve when all hits are already resolved', async () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-resolved']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-resolved': HIT_RESOLVED })
             });
-            // dispatchApi resolves → loading becomes false → unresolvedHits.length === 0 → auto-close
             await waitFor(() => {
-                expect(mockUpdateCase).toHaveBeenCalledWith({ status: 'resolved' });
+                expect(screen.getByRole('button', { name: i18n.t('confirm') })).toBeEnabled();
+            });
+            expect(mockUpdateCase).not.toHaveBeenCalled();
+            expect(mockClose).not.toHaveBeenCalled();
+        });
+        it('resolves case when confirm is clicked and all hits are already resolved', async () => {
+            render(_jsx(ResolveModal, { case: caseWithHits(['hit-resolved']), onConfirm: mockOnConfirm }), {
+                wrapper: createWrapper({ 'hit-resolved': HIT_RESOLVED })
             });
             await waitFor(() => {
+                expect(screen.getByRole('button', { name: i18n.t('confirm') })).toBeEnabled();
+            });
+            await user.click(screen.getByRole('button', { name: i18n.t('confirm') }));
+            await waitFor(() => {
+                expect(mockUpdateCase).toHaveBeenCalledWith({ status: 'resolved' });
                 expect(mockOnConfirm).toHaveBeenCalledTimes(1);
                 expect(mockClose).toHaveBeenCalledTimes(1);
             });
         });
-        it('does NOT auto-resolve while hits are still unresolved', async () => {
+        it('resolves case with unresolved hits when override option is selected', async () => {
             render(_jsx(ResolveModal, { case: caseWithHits(['hit-1']), onConfirm: mockOnConfirm }), {
                 wrapper: createWrapper({ 'hit-1': HIT_1 })
             });
-            // Wait for loading to complete: the unresolved hit's checkbox appears once the
-            // dispatchApi call settles and the LinearProgress opacity drops to 0.
-            await screen.findAllByRole('checkbox');
-            // Should not have auto-resolved
-            expect(mockUpdateCase).not.toHaveBeenCalled();
-            expect(mockClose).not.toHaveBeenCalled();
+            await waitFor(() => {
+                expect(getHitCheckboxes()).toHaveLength(1);
+            });
+            await user.click(screen.getByRole('checkbox', { name: i18n.t('modal.cases.resolve.allow_unresolved.aria_label') }));
+            await user.click(screen.getByRole('button', { name: i18n.t('confirm') }));
+            await waitFor(() => {
+                expect(mockAssess).not.toHaveBeenCalled();
+                expect(mockUpdateCase).toHaveBeenCalledWith({ status: 'resolved' });
+                expect(mockOnConfirm).toHaveBeenCalledTimes(1);
+                expect(mockClose).toHaveBeenCalledTimes(1);
+            });
         });
     });
 });

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/ActionIntroductionDocumentation.js

@@ -25,7 +25,7 @@ const ActionIntroductionDocumentation = () => {
     useEffect(() => {
         api.action.operations
             .get()
-            .then(_operations => _operations.filter(a => difference(a.roles, user.roles).length < 1))
+            .then(_operations => _operations.filter(a => difference(a.roles, user.roles).length < a.roles.length))
             .then(setOperations)
             // eslint-disable-next-line no-console
             .catch(console.debug);

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/en/retention.md.js

@@ -1 +1 @@
-export default "# Retention in Howler\n\nIn order to comply with organizational policies, Howler is configured to purge stale alerts after a specific amount of\ntime. On this instance, that duration is `duration`.\n\n## How Retention Works\n\nHowler uses an automated retention job that runs on a configurable schedule (typically nightly) to remove\nalerts that have exceeded their retention period. The system evaluates two criteria for deletion:\n\n1. **Standard Retention**: Alerts are deleted when `event.created` exceeds the configured retention period\n2. **Custom Expiry**: Alerts are deleted when the `howler.expiry` field indicates the alert should expire\n\nAn alert will be removed when **either** condition is met - whichever comes first.\n\n## Custom Expiry (`howler.expiry`)\n\nThe `howler.expiry` field allows detection engineers to set custom retention periods for specific alerts\nduring ingestion. This field overrides the standard retention calculation and is commonly used when:\n\n- Clients have requested shorter data retention periods than the deployment default\n- Specific operations require time-limited data storage (e.g., a cybersecurity operation where data can\n  only be retained for two weeks after ingest)\n- Regulatory requirements mandate earlier deletion for certain types of data\n\n```alert\nThe howler.expiry field can only shorten retention periods, not extend them. No matter\nwhat, alerts cannot be retained longer than the system-wide retention cutoff based on event.created.\n```\n\n## Configuration\n\nAdministrators can configure retention settings in the system configuration:\n\n```yaml\nsystem:\n  type: staging\n  retention:\n    limit_amount: 120      # Retention period duration\n    limit_unit: days       # Time unit (days, hours, etc.)\n    crontab: \"0 0 * * *\"   # Schedule (nightly at midnight)\n    enabled: true          # Whether retention is active\n```\n\n## User Interface\n\nTo communicate retention timing to users, see the example alert below:\n\n`alert`\n\nIn the top right, hovering over the timestamp will outline how long users have before the alert is\nremoved. In order to ensure compliance with policy, ensure that `event.created` matches the date the\nunderlying data was collected, allowing Howler to ensure data is purged in time.\n"
+export default "# Retention in Howler\n\nIn order to comply with organizational policies, Howler is configured to purge stale alerts after a specific amount of\ntime. On this instance, that duration is `duration`.\n\n## How Retention Works\n\nHowler uses an automated retention job that runs on a configurable schedule (typically nightly) to remove\nalerts that have exceeded their retention period. The system evaluates two criteria for deletion:\n\n1. **Standard Retention**: Alerts are deleted when `event.created` exceeds the configured retention period\n2. **Custom Expiry**: Alerts are deleted when the `howler.expiry` field indicates the alert should expire\n\nAn alert will be removed when **either** condition is met - whichever comes first.\n\n## Custom Expiry (`howler.expiry`)\n\nThe `howler.expiry` field allows detection engineers to set custom retention periods for specific alerts\nduring ingestion. This field overrides the standard retention calculation and is commonly used when:\n\n- Clients have requested shorter data retention periods than the deployment default\n- Specific operations require time-limited data storage (e.g., a cybersecurity operation where data can\n  only be retained for two weeks after ingest)\n- Regulatory requirements mandate earlier deletion for certain types of data\n\n```alert\nThe howler.expiry field can only shorten retention periods, not extend them. No matter\nwhat, alerts cannot be retained longer than the system-wide retention cutoff based on event.created.\n```\n\n## Configuration\n\nAdministrators can configure retention settings in the system configuration:\n\n```yaml\nsystem:\n  type: staging\n  retention:\n    limit_amount: 120 # Retention period duration\n    limit_unit: days # Time unit (days, hours, etc.)\n    crontab: '0 0 * * *' # Schedule (nightly at midnight)\n    enabled: true # Whether retention is active\n```\n\n## User Interface\n\nTo communicate retention timing to users, see the example alert below:\n\n`alert`\n\nIn the top right, hovering over the timestamp will outline how long users have before the alert is\nremoved. In order to ensure compliance with policy, ensure that `event.created` matches the date the\nunderlying data was collected, allowing Howler to ensure data is purged in time.\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/help/markdown/fr/retention.md.js

@@ -1 +1 @@
-export default "# R\u00e9tention dans Howler\n\nAfin de se conformer aux politiques organisationnelles, Howler est configur\u00e9 pour purger les alertes\np\u00e9rim\u00e9es apr\u00e8s une p\u00e9riode de temps sp\u00e9cifique. Dans cette instance, cette dur\u00e9e est `duration`.\n\n## Comment fonctionne la r\u00e9tention\n\nHowler utilise un travail de r\u00e9tention automatis\u00e9 qui s'ex\u00e9cute selon un calendrier configurable\n(g\u00e9n\u00e9ralement nocturne) pour supprimer les alertes qui ont d\u00e9pass\u00e9 leur p\u00e9riode de r\u00e9tention. Le syst\u00e8me\n\u00e9value deux crit\u00e8res de suppression :\n\n1. **R\u00e9tention standard** : Les alertes sont supprim\u00e9es lorsque `event.created` d\u00e9passe la p\u00e9riode de\n   r\u00e9tention configur\u00e9e\n2. **Expiration personnalis\u00e9e** : Les alertes sont supprim\u00e9es lorsque le champ `howler.expiry` indique\n   que l'alerte doit expirer\n\nUne alerte sera supprim\u00e9e lorsque **l'une ou l'autre** condition est remplie - selon celle qui arrive en\npremier.\n\n## Expiration personnalis\u00e9e (`howler.expiry`)\n\nLe champ `howler.expiry` permet aux ing\u00e9nieurs de d\u00e9tection de d\u00e9finir des p\u00e9riodes de r\u00e9tention\npersonnalis\u00e9es pour des alertes sp\u00e9cifiques lors de l'ingestion. Ce champ remplace le calcul de\nr\u00e9tention standard et est couramment utilis\u00e9 quand :\n\n- Les clients ont demand\u00e9 des p\u00e9riodes de r\u00e9tention de donn\u00e9es plus courtes que la valeur par d\u00e9faut\n  du d\u00e9ploiement\n- Des op\u00e9rations sp\u00e9cifiques n\u00e9cessitent un stockage de donn\u00e9es \u00e0 dur\u00e9e limit\u00e9e (par ex., une op\u00e9ration\n  de cybers\u00e9curit\u00e9 o\u00f9 les donn\u00e9es ne peuvent \u00eatre conserv\u00e9es que deux semaines apr\u00e8s ingestion)\n- Les exigences r\u00e9glementaires imposent une suppression plus pr\u00e9coce pour certains types de donn\u00e9es\n\n```alert\nLe champ howler.expiry ne peut que raccourcir les p\u00e9riodes de r\u00e9tention, pas les\nprolonger. Quoi qu'il arrive, les alertes ne peuvent pas \u00eatre conserv\u00e9es plus longtemps que la limite de\nr\u00e9tention syst\u00e8me bas\u00e9e sur event.created.\n```\n\n## Configuration\n\nLes administrateurs peuvent configurer les param\u00e8tres de r\u00e9tention dans la configuration syst\u00e8me :\n\n```yaml\nsystem:\n  type: staging\n  retention:\n    limit_amount: 120      # Dur\u00e9e de la p\u00e9riode de r\u00e9tention\n    limit_unit: days       # Unit\u00e9 de temps (days, hours, etc.)\n    crontab: \"0 0 * * *\"    # Calendrier (nocturne \u00e0 minuit)\n    enabled: true          # Si la r\u00e9tention est active\n```\n\n## Interface utilisateur\n\nAfin de communiquer le d\u00e9lai de r\u00e9tention aux utilisateurs, voir l'exemple d'alerte ci-dessous :\n\n`alert`\n\nEn haut \u00e0 droite, le survol de l'horodatage indique le temps dont dispose l'utilisateur avant que\nl'alerte ne soit supprim\u00e9e. Afin de se conformer aux politiques, assurez-vous que `event.created`\ncorrespond \u00e0 la date \u00e0 laquelle les donn\u00e9es sous-jacentes ont \u00e9t\u00e9 collect\u00e9es, permettant \u00e0 Howler de\ns'assurer que les donn\u00e9es sont purg\u00e9es \u00e0 temps.\n"
+export default "# R\u00e9tention dans Howler\n\nAfin de se conformer aux politiques organisationnelles, Howler est configur\u00e9 pour purger les alertes\np\u00e9rim\u00e9es apr\u00e8s une p\u00e9riode de temps sp\u00e9cifique. Dans cette instance, cette dur\u00e9e est `duration`.\n\n## Comment fonctionne la r\u00e9tention\n\nHowler utilise un travail de r\u00e9tention automatis\u00e9 qui s'ex\u00e9cute selon un calendrier configurable\n(g\u00e9n\u00e9ralement nocturne) pour supprimer les alertes qui ont d\u00e9pass\u00e9 leur p\u00e9riode de r\u00e9tention. Le syst\u00e8me\n\u00e9value deux crit\u00e8res de suppression :\n\n1. **R\u00e9tention standard** : Les alertes sont supprim\u00e9es lorsque `event.created` d\u00e9passe la p\u00e9riode de\n   r\u00e9tention configur\u00e9e\n2. **Expiration personnalis\u00e9e** : Les alertes sont supprim\u00e9es lorsque le champ `howler.expiry` indique\n   que l'alerte doit expirer\n\nUne alerte sera supprim\u00e9e lorsque **l'une ou l'autre** condition est remplie - selon celle qui arrive en\npremier.\n\n## Expiration personnalis\u00e9e (`howler.expiry`)\n\nLe champ `howler.expiry` permet aux ing\u00e9nieurs de d\u00e9tection de d\u00e9finir des p\u00e9riodes de r\u00e9tention\npersonnalis\u00e9es pour des alertes sp\u00e9cifiques lors de l'ingestion. Ce champ remplace le calcul de\nr\u00e9tention standard et est couramment utilis\u00e9 quand :\n\n- Les clients ont demand\u00e9 des p\u00e9riodes de r\u00e9tention de donn\u00e9es plus courtes que la valeur par d\u00e9faut\n  du d\u00e9ploiement\n- Des op\u00e9rations sp\u00e9cifiques n\u00e9cessitent un stockage de donn\u00e9es \u00e0 dur\u00e9e limit\u00e9e (par ex., une op\u00e9ration\n  de cybers\u00e9curit\u00e9 o\u00f9 les donn\u00e9es ne peuvent \u00eatre conserv\u00e9es que deux semaines apr\u00e8s ingestion)\n- Les exigences r\u00e9glementaires imposent une suppression plus pr\u00e9coce pour certains types de donn\u00e9es\n\n```alert\nLe champ howler.expiry ne peut que raccourcir les p\u00e9riodes de r\u00e9tention, pas les\nprolonger. Quoi qu'il arrive, les alertes ne peuvent pas \u00eatre conserv\u00e9es plus longtemps que la limite de\nr\u00e9tention syst\u00e8me bas\u00e9e sur event.created.\n```\n\n## Configuration\n\nLes administrateurs peuvent configurer les param\u00e8tres de r\u00e9tention dans la configuration syst\u00e8me :\n\n```yaml\nsystem:\n  type: staging\n  retention:\n    limit_amount: 120 # Dur\u00e9e de la p\u00e9riode de r\u00e9tention\n    limit_unit: days # Unit\u00e9 de temps (days, hours, etc.)\n    crontab: '0 0 * * *' # Calendrier (nocturne \u00e0 minuit)\n    enabled: true # Si la r\u00e9tention est active\n```\n\n## Interface utilisateur\n\nAfin de communiquer le d\u00e9lai de r\u00e9tention aux utilisateurs, voir l'exemple d'alerte ci-dessous :\n\n`alert`\n\nEn haut \u00e0 droite, le survol de l'horodatage indique le temps dont dispose l'utilisateur avant que\nl'alerte ne soit supprim\u00e9e. Afin de se conformer aux politiques, assurez-vous que `event.created`\ncorrespond \u00e0 la date \u00e0 laquelle les donn\u00e9es sous-jacentes ont \u00e9t\u00e9 collect\u00e9es, permettant \u00e0 Howler de\ns'assurer que les donn\u00e9es sont purg\u00e9es \u00e0 temps.\n"

package/components/routes/hits/search/shared/CustomSpan.js

@@ -11,16 +11,16 @@ import { useContextSelector } from 'use-context-selector';
 const CustomSpan = () => {
     const { t } = useTranslation();
     const span = useContextSelector(ParameterContext, ctx => ctx.span);
-    const defaultStartDate = dayjs().subtract(2, 'days');
-    const defaultEndDate = dayjs().subtract(1, 'day');
-    const startDate = useContextSelector(ParameterContext, ctx => ctx.startDate ? dayjs(ctx.startDate) : defaultStartDate);
     const setCustomSpan = useContextSelector(ParameterContext, ctx => ctx.setCustomSpan);
-    const endDate = useContextSelector(ParameterContext, ctx => (ctx.endDate ? dayjs(ctx.endDate) : defaultEndDate));
+    const startDate = useContextSelector(ParameterContext, ctx => (ctx.startDate ? dayjs(ctx.startDate) : null));
+    const endDate = useContextSelector(ParameterContext, ctx => (ctx.endDate ? dayjs(ctx.endDate) : null));
     useEffect(() => {
-        if (span?.endsWith('custom')) {
-            setCustomSpan(startDate.toISOString(), endDate.toISOString());
+        if (span?.endsWith('custom') && (!startDate || !endDate)) {
+            const _startDate = startDate ?? dayjs().subtract(2, 'day');
+            const _endDate = endDate ?? dayjs().subtract(1, 'day');
+            setCustomSpan(dayjs.min(_startDate, _endDate).toISOString(), dayjs.max(_startDate, _endDate).toISOString());
         }
     }, [endDate, setCustomSpan, span, startDate]);
-    return span?.endsWith('custom') ? (_jsx(LocalizationProvider, { dateAdapter: AdapterDayjs, children: _jsxs(Stack, { direction: "row", spacing: 1, useFlexGap: true, flexWrap: "wrap", children: [_jsx(DateTimePicker, { sx: { minWidth: '175px', flexGrow: 1, marginTop: 1 }, slotProps: { textField: { size: 'small' } }, label: t('date.select.start'), value: startDate ? dayjs(startDate) : dayjs().subtract(1, 'days'), maxDate: endDate, onChange: (newStartDate) => setCustomSpan(newStartDate.toISOString(), endDate.toISOString()), ampm: false, disableFuture: true }), _jsx(DateTimePicker, { sx: { minWidth: '175px', flexGrow: 1, marginTop: 1 }, slotProps: { textField: { size: 'small' } }, label: t('date.select.end'), value: endDate, minDate: startDate, onChange: (newEndDate) => setCustomSpan(startDate.toISOString(), newEndDate.toISOString()), ampm: false, disableFuture: true })] }) })) : null;
+    return span?.endsWith('custom') ? (_jsx(LocalizationProvider, { dateAdapter: AdapterDayjs, children: _jsxs(Stack, { direction: "row", spacing: 1, useFlexGap: true, flexWrap: "wrap", children: [_jsx(DateTimePicker, { sx: { minWidth: '175px', flexGrow: 1, marginTop: 1 }, slotProps: { textField: { size: 'small' } }, label: t('date.select.start'), value: startDate ? dayjs(startDate) : dayjs().subtract(1, 'days'), maxDateTime: endDate, onChange: (newStartDate) => setCustomSpan(newStartDate.toISOString(), endDate.toISOString()), ampm: false, disableFuture: true }), _jsx(DateTimePicker, { sx: { minWidth: '175px', flexGrow: 1, marginTop: 1 }, slotProps: { textField: { size: 'small' } }, label: t('date.select.end'), value: endDate, minDateTime: startDate, onChange: (newEndDate) => setCustomSpan(startDate.toISOString(), newEndDate.toISOString()), ampm: false, disableFuture: true })] }) })) : null;
 };
 export default memo(CustomSpan);

package/components/routes/hits/search/shared/CustomSpan.test.d.ts

@@ -0,0 +1 @@
+export {};