@cccsaurora/howler-ui 2.14.0-dev.259 → 2.14.0-dev.264

package/components/routes/help/ApiDocumentation.tsx

@@ -0,0 +1,217 @@
+import { Help } from '@mui/icons-material';
+import {
+  Chip,
+  Paper,
+  Stack,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableRow,
+  Tooltip,
+  Typography,
+  useMediaQuery,
+  useTheme
+} from '@mui/material';
+import api from 'api';
+import type { HelpResponse } from 'api/help';
+import { useAppUser } from 'commons/components/app/hooks';
+import PageCenter from 'commons/components/pages/PageCenter';
+import Markdown from 'components/elements/display/Markdown';
+import useMyApi from 'components/hooks/useMyApi';
+import { useScrollRestoration } from 'components/hooks/useScrollRestoration';
+import type { HowlerUser } from 'models/entities/HowlerUser';
+import { useEffect, useState, type FC } from 'react';
+import { Trans, useTranslation } from 'react-i18next';
+import { Fragment } from 'react/jsx-runtime';
+
+const APIKEY_LABELS = {
+  R: 'apikey.read',
+  W: 'apikey.write',
+  E: 'apikey.extended',
+  I: 'apikey.impersonate'
+};
+
+const ApiDocumentation: FC = () => {
+  const { t } = useTranslation();
+  const { user } = useAppUser<HowlerUser>();
+  const { dispatchApi } = useMyApi();
+  const theme = useTheme();
+  useScrollRestoration();
+
+  const isLg = useMediaQuery(theme.breakpoints.down('lg'));
+
+  const [data, setData] = useState<HelpResponse>(null);
+
+  useEffect(() => {
+    dispatchApi(api.help.get()).then(setData);
+  }, [dispatchApi]);
+
+  if (!data) {
+    return (
+      <PageCenter margin={4} maxWidth="1750px" width="100%" textAlign="left">
+        {t('loading')}
+      </PageCenter>
+    );
+  }
+
+  return (
+    <PageCenter margin={4} maxWidth="1750px" width="100%" textAlign="left">
+      <Stack spacing={2}>
+        <Typography variant="h4">{t('page.documentation.categories')}</Typography>
+        <TableContainer component={Paper}>
+          <Table sx={{ '& td': { verticalAlign: 'top' }, '& tr:last-of-type > td': { border: 0 } }}>
+            <TableHead>
+              <TableRow>
+                <TableCell>{t('page.documentation.categories.category')}</TableCell>
+                <TableCell>{t('page.documentation.categories.description')}</TableCell>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {Object.keys(data.blueprints).map(key => (
+                <TableRow key={key} sx={{ width: '100%' }}>
+                  <TableCell>
+                    <code>{key}</code>
+                  </TableCell>
+                  <TableCell>{data.blueprints[key]}</TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </TableContainer>
+        <Typography variant="h4" sx={{ pt: 4 }}>
+          {t('page.documentation.endpoints')}
+        </Typography>
+        <TableContainer component={Paper}>
+          <Table
+            sx={{
+              '& td': { verticalAlign: 'top' },
+              '& tr:last-of-type > td': { border: 0 },
+              '& pre': {
+                backgroundColor: 'background.paper',
+                padding: 0.75,
+                borderRadius: '5px'
+              },
+              '& :not(pre) > code': {
+                backgroundColor: 'background.paper',
+                padding: 0.75,
+                borderRadius: '5px'
+              }
+            }}
+          >
+            <TableHead>
+              <TableRow>
+                <Tooltip placement="top-start" title={<Trans i18nKey="page.documentation.endpoint.explanation" />}>
+                  <TableCell>
+                    {t('page.documentation.endpoint')}
+                    <Help sx={{ height: '16px', width: '16px', ml: 1 }} />
+                  </TableCell>
+                </Tooltip>
+                <Tooltip placement="top-start" title={<Trans i18nKey="page.documentation.required_type.explanation" />}>
+                  <TableCell>
+                    {t('page.documentation.required_type')}
+                    <Help sx={{ height: '16px', width: '16px', ml: 1 }} />
+                  </TableCell>
+                </Tooltip>
+                <Tooltip placement="top-start" title={<Trans i18nKey="page.documentation.required_priv.explanation" />}>
+                  <TableCell>
+                    {t('page.documentation.required_priv')}
+                    <Help sx={{ height: '16px', width: '16px', ml: 1 }} />
+                  </TableCell>
+                </Tooltip>
+                {!isLg && (
+                  <Tooltip placement="top-start" title={<Trans i18nKey="page.documentation.description.explanation" />}>
+                    <TableCell>
+                      {t('page.documentation.description')}
+                      <Help sx={{ height: '16px', width: '16px', ml: 1 }} />
+                    </TableCell>
+                  </Tooltip>
+                )}
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {data.apis.map(endpoint => {
+                const documentationCell = (
+                  <Markdown
+                    md={endpoint.description
+                      .replace(/(:\n)(None)/g, '$1\n`$2`')
+                      .replace(/(\S+)\s+=>\s+(.+)/g, '\n`$1`: $2\n')
+                      .replace(
+                        /(Data Block:\n)([\s\S]+)(Result Example:)/,
+                        (__, p1: string, p2: string, p3: string) => `${p1}\`\`\`\n${p2.trim()}\n\`\`\`\n${p3}`
+                      )
+                      .replace(
+                        /(Result Example:\n)([\s\S]+)$/,
+                        (__, p1: string, p2: string) => `${p1}\`\`\`\n${p2.trim()}\n\`\`\``
+                      )}
+                  />
+                );
+
+                return (
+                  <Fragment key={endpoint.id}>
+                    <TableRow style={{ marginBottom: '1rem' }} sx={[isLg && { '& > td': { borderBottom: 0 } }]}>
+                      <TableCell>
+                        <Stack direction="column" spacing={1} alignItems="start">
+                          <Typography>{endpoint.name}</Typography>
+                          <code>{endpoint.path}</code>
+                          <Stack direction="row" spacing={1}>
+                            {endpoint.complete ? (
+                              <Chip size="small" label="Stable" color="success" />
+                            ) : (
+                              <Chip size="small" label="Unstable" color="error" />
+                            )}
+                            {endpoint.protected ? (
+                              <Chip size="small" label="Protected" color="warning" />
+                            ) : (
+                              <Chip size="small" label="Unprotected" />
+                            )}
+                          </Stack>
+                          <Stack spacing={1} direction="row">
+                            {endpoint.methods.map(m => (
+                              <Chip key={m} size="small" label={m} />
+                            ))}
+                          </Stack>
+                          {endpoint.ui_only && <Chip size="small" label="UI Only" />}
+                        </Stack>
+                      </TableCell>
+                      <TableCell>
+                        <Stack spacing={1} direction="row">
+                          {endpoint.required_type.map(type => (
+                            <Chip
+                              key={type}
+                              size="small"
+                              label={type}
+                              color={user.roles?.includes(type) ? 'success' : 'default'}
+                            />
+                          ))}
+                        </Stack>
+                      </TableCell>
+                      <TableCell>
+                        <Stack spacing={1} direction="row">
+                          {endpoint.required_priv.map((p: 'R' | 'W' | 'E' | 'I') => (
+                            <Chip key={p} size="small" label={t(APIKEY_LABELS[p])} />
+                          ))}
+                        </Stack>
+                      </TableCell>
+                      {!isLg && <TableCell>{documentationCell}</TableCell>}
+                    </TableRow>
+                    {isLg && (
+                      <TableRow>
+                        <TableCell colSpan={3} sx={{ '& pre': { whiteSpace: 'pre-wrap' } }}>
+                          {documentationCell}
+                        </TableCell>
+                      </TableRow>
+                    )}
+                  </Fragment>
+                );
+              })}
+            </TableBody>
+          </Table>
+        </TableContainer>
+      </Stack>
+    </PageCenter>
+  );
+};
+
+export default ApiDocumentation;

package/components/routes/help/AuthDocumentation.tsx

@@ -0,0 +1,26 @@
+import PageCenter from 'commons/components/pages/PageCenter';
+import Markdown from 'components/elements/display/Markdown';
+import { useScrollRestoration } from 'components/hooks/useScrollRestoration';
+import type { FC } from 'react';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import AUTH_EN from './markdown/en/authentication.md';
+import AUTH_FR from './markdown/fr/authentication.md';
+
+const AuthDocumentation: FC = () => {
+  const { i18n } = useTranslation();
+  useScrollRestoration();
+
+  const md = useMemo(
+    () => (i18n.language === 'en' ? AUTH_EN : AUTH_FR).replace(/\$CURRENT_URL/g, window.location.origin),
+    [i18n.language]
+  );
+
+  return (
+    <PageCenter margin={4} width="100%" textAlign="left">
+      <Markdown md={md} />
+    </PageCenter>
+  );
+};
+export default AuthDocumentation;

package/components/routes/help/BundleDocumentation.tsx

@@ -0,0 +1,17 @@
+import Markdown from 'components/elements/display/Markdown';
+import type { FC } from 'react';
+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: FC = () => {
+  const { i18n } = useTranslation();
+
+  const md = useMemo(() => (i18n.language === 'en' ? BUNDLES_EN : BUNDLES_FR), [i18n.language]);
+
+  return <Markdown md={md} />;
+};
+
+export default BundleDocumentation;

package/components/routes/help/ClientDocumentation.tsx

@@ -0,0 +1,27 @@
+import PageCenter from 'commons/components/pages/PageCenter';
+import Markdown from 'components/elements/display/Markdown';
+import type { FC } from 'react';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useScrollRestoration } from 'components/hooks/useScrollRestoration';
+import CLIENT_EN from './markdown/en/client.md';
+import CLIENT_FR from './markdown/fr/client.md';
+
+const ClientDocumentation: FC = () => {
+  const { i18n } = useTranslation();
+  useScrollRestoration();
+
+  const md = useMemo(
+    () => (i18n.language === 'en' ? CLIENT_EN : CLIENT_FR).replace(/\$CURRENT_URL/g, window.location.origin),
+    [i18n.language]
+  );
+
+  return (
+    <PageCenter margin={4} width="100%" textAlign="left">
+      <Markdown md={md} />
+    </PageCenter>
+  );
+};
+
+export default ClientDocumentation;

package/components/routes/help/Help.tsx

@@ -0,0 +1,96 @@
+import { HelpCenter, OpenInNew } from '@mui/icons-material';
+import {
+  Button,
+  Card,
+  CardActions,
+  CardContent,
+  CardHeader,
+  Divider,
+  Grid,
+  IconButton,
+  Stack,
+  Typography
+} from '@mui/material';
+import type { AppLeftNavGroup } from 'commons/components/app/AppConfigs';
+import PageCenter from 'commons/components/pages/PageCenter';
+import useMyPreferences from 'components/hooks/useMyPreferences';
+import { useScrollRestoration } from 'components/hooks/useScrollRestoration';
+import howlerPluginStore from 'plugins/store';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import { usePluginStore } from 'react-pluggable';
+import { Link } from 'react-router-dom';
+
+const HelpDashboard = () => {
+  const { t } = useTranslation(['translation', 'helpMain']);
+  const { leftnav } = useMyPreferences();
+  const pluginStore = usePluginStore();
+
+  useScrollRestoration();
+
+  const tabs = useMemo(
+    () => ({
+      'help.hit': ['schema', 'header', 'bundle', 'links'],
+      'help.actions': ['introduction', ...howlerPluginStore.operations]
+    }),
+    []
+  );
+
+  const links = useMemo(
+    () =>
+      (
+        leftnav.elements.find(el => el.type === 'group' && el.element.id === 'help')!.element as AppLeftNavGroup
+      ).items.filter(_item => _item.id !== 'help.main'),
+    [leftnav.elements]
+  );
+
+  return (
+    <PageCenter margin={4} width="100%" maxWidth="1750px" textAlign="left">
+      <Stack spacing={1}>
+        <Typography variant="h3" sx={{ display: 'flex', flexDirection: 'row', alignItems: 'center' }}>
+          <HelpCenter fontSize="inherit" sx={{ mr: 1 }} />
+          <span>{t('page.help.title')}</span>
+        </Typography>
+        <Divider sx={theme => ({ marginLeft: `${theme.spacing(1)} !important` })} />
+        <Grid container spacing={1} sx={{ pr: 1 }}>
+          {links.map(link => (
+            <Grid item xs={12} md={3} key={link.id} sx={{ display: 'flex' }}>
+              <Card sx={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
+                <CardHeader
+                  title={
+                    <Stack
+                      direction="row"
+                      alignItems="center"
+                      sx={{ '& svg': { fontSize: 'inherit' }, '& > span': { ml: 1 } }}
+                    >
+                      {link.icon}
+                      <span>{t(link.i18nKey)}</span>
+                      <IconButton component={Link} to={link.route} sx={{ ml: 'auto' }}>
+                        <OpenInNew color="primary" fontSize="inherit" />
+                      </IconButton>
+                    </Stack>
+                  }
+                />
+                <CardContent sx={{ flex: 1 }}>
+                  <Typography>{t(`helpMain:${link.i18nKey}.description`)}</Typography>
+                </CardContent>
+                {tabs[link.id] && (
+                  <CardActions>
+                    {tabs[link.id].map(tab => (
+                      <Button key={tab} size="small" component={Link} to={`${link.route}?tab=${tab}`}>
+                        {tab}
+                      </Button>
+                    ))}
+                  </CardActions>
+                )}
+              </Card>
+            </Grid>
+          ))}
+        </Grid>
+        {howlerPluginStore.plugins.map(plugin => pluginStore.executeFunction(`${plugin}.help`))}
+      </Stack>
+    </PageCenter>
+  );
+};
+
+export default HelpDashboard;

package/components/routes/help/HitBannerDocumentation.tsx

@@ -0,0 +1,71 @@
+import { CardContent, Divider, Typography } from '@mui/material';
+import HowlerCard from 'components/elements/display/HowlerCard';
+import JSONViewer from 'components/elements/display/json/JSONViewer';
+import HitBanner from 'components/elements/hit/HitBanner';
+import { HitLayout } from 'components/elements/hit/HitLayout';
+import type { Hit } from 'models/entities/generated/Hit';
+import type { FC } from 'react';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const HitBannerDocumentation: FC = () => {
+  const { t } = useTranslation();
+
+  const dummyHit = useMemo<Hit>(
+    () => ({
+      timestamp: '2023-02-11T15:10:31.585826Z',
+      howler: {
+        id: 'howler.id',
+        analytic: 'howler.analytic',
+        detection: 'howler.detection',
+        assignment: 'howler.assignment',
+        hash: 'howler.hash',
+        outline: {
+          threat: 'howler.outline.threat',
+          target: 'howler.outline.target',
+          indicators: ['howler.outline.indicators'],
+          summary: 'howler.outline.summary'
+        },
+        escalation: 'howler.escalation',
+        status: 'howler.status'
+      },
+      event: {
+        created: '2023-02-11T15:10:31.585826Z',
+        provider: 'event.provider'
+      },
+      organization: {
+        id: 'organization.id',
+        name: 'organization.name'
+      },
+      threat: {
+        tactic: {
+          id: 'threat.tactic.id',
+          name: 'threat.tactic.name'
+        },
+        technique: {
+          id: 'threat.technique.id',
+          name: 'threat.technique.name'
+        }
+      }
+    }),
+    []
+  );
+
+  return (
+    <>
+      <h1>{t('help.hit.banner.title')}</h1>
+      <Typography variant="body1">{t('help.hit.banner.description')}</Typography>
+      <Divider orientation="horizontal" sx={{ my: 2 }} />
+      <HowlerCard sx={{ mb: 2 }}>
+        <CardContent>
+          <HitBanner hit={dummyHit} layout={HitLayout.COMFY} />
+        </CardContent>
+      </HowlerCard>
+      <Typography variant="body1">{t('help.hit.banner.json')}</Typography>
+      <Divider orientation="horizontal" sx={{ my: 2 }} />
+      <JSONViewer data={dummyHit} />
+    </>
+  );
+};
+
+export default HitBannerDocumentation;

package/components/routes/help/HitDocumentation.tsx

@@ -0,0 +1,77 @@
+import { Box, Stack, Tab, Typography, useMediaQuery, useTheme } from '@mui/material';
+import PageCenter from 'commons/components/pages/PageCenter';
+import { useScrollRestoration } from 'components/hooks/useScrollRestoration';
+import type { FC } from 'react';
+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';
+import HitLinksDocumentation from './HitLinksDocumentation';
+import HitSchemaDocumentation from './HitSchemaDocumentation';
+
+const HitDocumentation: FC = () => {
+  const { t } = useTranslation();
+  const theme = useTheme();
+  const useHorizontal = useMediaQuery(theme.breakpoints.down(1700));
+  useScrollRestoration();
+
+  const [searchParams, setSearchParams] = useSearchParams();
+  const [tab, setTab] = useState(searchParams.get('tab') ?? 'schema');
+
+  const onChange = useCallback(
+    (_tab: string) => {
+      setTab(_tab);
+      searchParams.set('tab', _tab);
+      setSearchParams(new URLSearchParams(searchParams));
+    },
+    [searchParams, setSearchParams]
+  );
+
+  return (
+    <PageCenter margin={4} width="100%" maxWidth="1750px" textAlign="left">
+      <Stack sx={{ flexDirection: useHorizontal ? 'column' : 'row', '& h1': { mt: 0 } }}>
+        <HelpTabs value={tab}>
+          <Tab
+            label={<Typography variant="caption">{t('help.hit.schema.title')}</Typography>}
+            value="schema"
+            onClick={() => onChange('schema')}
+          />
+          <Tab
+            label={<Typography variant="caption">{t('help.hit.banner.title')}</Typography>}
+            value="header"
+            onClick={() => onChange('header')}
+          />
+          <Tab
+            label={<Typography variant="caption">{t('help.hit.bundle.title')}</Typography>}
+            value="bundle"
+            onClick={() => onChange('bundle')}
+          />
+          <Tab
+            label={<Typography variant="caption">{t('help.hit.links.title')}</Typography>}
+            value="links"
+            onClick={() => onChange('links')}
+          />
+          <Tab
+            label={<Typography variant="caption">{t('help.hit.labels.title')}</Typography>}
+            value="labels"
+            onClick={() => onChange('labels')}
+          />
+        </HelpTabs>
+        <Box>
+          {{
+            bundle: () => <BundleDocumentation />,
+            header: () => <HitBannerDocumentation />,
+            links: () => <HitLinksDocumentation />,
+            labels: () => <HitLabelsDocumentation />,
+            schema: () => <HitSchemaDocumentation />
+          }[tab]()}
+        </Box>
+      </Stack>
+    </PageCenter>
+  );
+};
+
+export default HitDocumentation;

package/components/routes/help/HitLabelsDocumentation.tsx

@@ -0,0 +1,57 @@
+import type { FC } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { Chip, Paper, Stack, Table, TableBody, TableCell, TableContainer, TableHead, TableRow } from '@mui/material';
+import { capitalize } from 'lodash-es';
+import { LABEL_TYPES } from 'utils/constants';
+
+const HitLabelsDocumentation: FC = () => {
+  const { t } = useTranslation();
+
+  return (
+    <Stack>
+      <h1>{t('help.hit.labels.title')}</h1>
+      <TableContainer component={Paper}>
+        <Table>
+          <TableHead>
+            <TableRow>
+              <TableCell>{t('page.documentation.labels.name')}</TableCell>
+              <TableCell>{t('page.documentation.labels.description')}</TableCell>
+              <TableCell>{t('page.documentation.labels.example')}</TableCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {Object.entries(LABEL_TYPES).map(([label, details]) => (
+              <TableRow key={label}>
+                <TableCell>{capitalize(label)}</TableCell>
+                <TableCell>{t(`hit.label.category.${label}`).replace(/.+ - /, '')}</TableCell>
+                <TableCell>
+                  <Chip
+                    icon={details?.icon ?? undefined}
+                    variant="filled"
+                    size="small"
+                    label={label}
+                    sx={[
+                      {
+                        mr: 1,
+                        mb: 1
+                      },
+                      details?.color && {
+                        '&, & svg': {
+                          color: theme => theme.palette.getContrastText(details.color) + ' !important'
+                        },
+                        backgroundColor: details.color
+                      }
+                    ]}
+                  />
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </TableContainer>
+    </Stack>
+  );
+};
+
+export default HitLabelsDocumentation;

package/components/routes/help/HitLinksDocumentation.tsx

@@ -0,0 +1,23 @@
+import Markdown from 'components/elements/display/Markdown';
+import type { FC } from 'react';
+import { useContext, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { ApiConfigContext } from 'components/app/providers/ApiConfigProvider';
+import LINKS_EN from './markdown/en/links.md';
+import LINKS_FR from './markdown/fr/links.md';
+
+const HitLinksDocumentation: FC = () => {
+  const { i18n } = useTranslation();
+
+  const { config } = useContext(ApiConfigContext);
+
+  const md = useMemo(() => {
+    const appList = config.configuration.ui.apps.map(a => `- \`${a.name.toLowerCase()}\``).join('\n');
+
+    return (i18n.language === 'en' ? LINKS_EN : LINKS_FR).replace('$APP_LIST', appList);
+  }, [config.configuration.ui.apps, i18n.language]);
+
+  return <Markdown md={md} />;
+};
+export default HitLinksDocumentation;