Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -427,6 +427,28 @@ flowchart TB

Usage of SOARCA-GUI is described here: https://cossas.github.io/SOARCA/docs/

### Visual playbook editor

- Collapse either side panel with its chevron button. A primary-coloured canvas-facing border marks a collapsed panel.
- Right-click the canvas, a step, a connection or a connection badge for its actions. Hover a submenu or use the arrow keys to open its choices.
- Hold Shift and drag to select several steps, then drag the selection to move them together.
- Ctrl-click (Cmd-click on macOS) adds a step to the selection or removes it. The "Controls" section under the step list has the full list of controls.
- The properties panel groups fields in tabs. A step has Details, Execution, Variables and Advanced. The playbook has Metadata, Resources and Advanced. Fields without a form input, such as extensions, are edited as JSON in the Advanced tab.
- The editor sets `id`, `created_by`, `created` and `modified` itself, so the panel does not show them.
- Lists such as playbook types and labels use searchable selects. Type a new value and press Enter to add one that is not in the list.
- Variables, agents, targets and authentication info are rows that expand one at a time. The input for a variable's value follows its type.
- Valid from and valid until are shown and typed in your local time zone. The playbook stores them in UTC.
- Fields with a red asterisk are required by CACAO 2.0. Save is blocked while a required field is empty or a JSON box has invalid JSON. It then opens the step and tab with the problem. Missing connections are warnings and do not block saving.
- The read-only diagram supports panning and step details. Use its zoom buttons to change the zoom.
- Leaving the visual editor with unsaved changes asks for confirmation, including in-app navigation, reloads and closing the tab.

## Acknowledgements

The visual playbook editor was written from scratch for SOARCA-GUI, using these projects as a reference for CACAO concepts:

- [CACAO Roaster](https://github.com/opencybersecurityalliance/cacao-roaster) by the Open Cybersecurity Alliance (Apache-2.0), a browser-based editor for CACAO v2.0 playbooks.
- [CACAO Layout Extension](https://github.com/cyentific-rni/cacao-layout-extension) by Cyentific AS, now maintained by the [OASIS CACAO TC](https://github.com/oasis-tcs/cacao) (MIT, Copyright (c) 2023 Cyentific). The editor stores step positions under this extension's id (`extension-definition--418ee24c-9cb1-46d9-afa5-309e01aabc7f`).

## Contributing

Want to contribute to this project? Please keep in mind the following rules:
Expand Down
753 changes: 727 additions & 26 deletions package-lock.json

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,18 @@
"test": "vitest"
},
"dependencies": {
"@dagrejs/dagre": "^3.1.3",
"@tabler/icons-react": "^3.49.0",
"@tanstack/react-query": "^4.42.0",
"@xyflow/react": "^12.12.0",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"oidc-client-ts": "^3.5.0",
"react": "^19.2.0",
"react-dom": "^19.2.0",
"react-hot-toast": "^2.6.0",
"react-router": "^7.12.0",
"react-select": "^5.10.2",
"styled-components": "^6.3.6"
},
"devDependencies": {
Expand Down
109 changes: 69 additions & 40 deletions src/App.tsx
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
import { lazy, Suspense } from "react";
import { Navigate, Route, Routes } from "react-router";
import { AuthGate, PermissionGate } from "@/auth/AuthGate";
import { Permissions } from "@/auth/permissions";

import { ToasterSetup } from "./ToasterSetup";
import { CenteredCardContent, Spinner, ThemeSize } from "./components";
import { LoginPage } from "./pages/LoginPage";
import { NotFoundPage } from "./pages/NotFoundPage";
import { PlaceholderPage } from "./pages/PlaceholderPage";
Expand All @@ -11,11 +13,34 @@ import { SettingsPage } from "./pages/main-page/SettingsPage";
import { ExecutionDetailPage } from "./pages/main-page/monitoring-page/ExecutionDetailPage";
import { MonitoringPage } from "./pages/main-page/monitoring-page/MonitoringPage";
import { PlaybookCreatePage } from "./pages/main-page/playbooks-page/PlaybookCreatePage";
import { PlaybookEditPage } from "./pages/main-page/playbooks-page/PlaybookEditPage";
import { PlaybooksPage } from "./pages/main-page/playbooks-page/PlaybooksPage";
import { PlaybookDetailPage } from "./pages/main-page/playbooks-page/playbook-detail-page/PlaybookDetailPage";
import { PATHS } from "./utils";

// The visual editor pulls in React Flow, so it is only loaded when opened.
const PlaybookVisualEditPage = lazy(() =>
import(
"./pages/main-page/playbooks-page/visual-editor/pages/PlaybookVisualEditPage"
).then((m) => ({ default: m.PlaybookVisualEditPage })),
);
const PlaybookVisualCreatePage = lazy(() =>
import(
"./pages/main-page/playbooks-page/visual-editor/pages/PlaybookVisualCreatePage"
).then((m) => ({ default: m.PlaybookVisualCreatePage })),
);

const withSuspense = (page: React.ReactNode) => (
<Suspense
fallback={
<CenteredCardContent>
<Spinner $size={ThemeSize.Medium} />
</CenteredCardContent>
}
>
{page}
</Suspense>
);

function App() {
return (
<>
Expand All @@ -25,45 +50,49 @@ function App() {
<Route path={PATHS.LOGIN_CALLBACK} element={<LoginPage />} />
<Route path={PATHS.NOT_FOUND} element={<NotFoundPage />} />
<Route path={PATHS.BASE} element={<MainPage />}>
<Route element={<AuthGate />}>
<Route index element={<Navigate to={PATHS.DASHBOARD} replace />} />
<Route
path={PATHS.DASHBOARD}
element={<PlaceholderPage content="⚠️ Dashboard coming soon!" />}
/>
<Route
element={<PermissionGate permission={Permissions.PlaybookRead} />}
>
<Route path={PATHS.PLAYBOOKS.BASE} element={<PlaybooksPage />} />
<Route
path={PATHS.PLAYBOOKS.DETAIL}
element={<PlaybookDetailPage />}
/>
<Route
path={PATHS.MONITORING.BASE}
element={<MonitoringPage />}
/>
<Route
path={PATHS.MONITORING.DETAIL}
element={<ExecutionDetailPage />}
/>
</Route>
<Route
element={
<PermissionGate permission={Permissions.PlaybookWrite} />
}
>
<Route
path={PATHS.PLAYBOOKS.NEW}
element={<PlaybookCreatePage />}
/>
<Route
path={PATHS.PLAYBOOKS.EDIT}
element={<PlaybookEditPage />}
/>
</Route>
<Route path={PATHS.SETTINGS} element={<SettingsPage />} />
</Route>
<Route element={<AuthGate />}>
<Route index element={<Navigate to={PATHS.DASHBOARD} replace />} />
<Route
path={PATHS.DASHBOARD}
element={<PlaceholderPage content="⚠️ Dashboard coming soon!" />}
/>
<Route
element={<PermissionGate permission={Permissions.PlaybookRead} />}
>
<Route path={PATHS.PLAYBOOKS.BASE} element={<PlaybooksPage />} />
<Route
path={PATHS.PLAYBOOKS.DETAIL}
element={<PlaybookDetailPage />}
/>
<Route
path={PATHS.MONITORING.BASE}
element={<MonitoringPage />}
/>
<Route
path={PATHS.MONITORING.DETAIL}
element={<ExecutionDetailPage />}
/>
</Route>
<Route
element={
<PermissionGate permission={Permissions.PlaybookWrite} />
}
>
<Route
path={PATHS.PLAYBOOKS.UPLOAD}
element={<PlaybookCreatePage />}
/>
<Route
path={PATHS.PLAYBOOKS.NEW}
element={withSuspense(<PlaybookVisualCreatePage />)}
/>
<Route
path={PATHS.PLAYBOOKS.EDIT}
element={withSuspense(<PlaybookVisualEditPage />)}
/>
</Route>
<Route path={PATHS.SETTINGS} element={<SettingsPage />} />
</Route>
</Route>
<Route path="*" element={<Navigate to={PATHS.NOT_FOUND} replace />} />
</Routes>
Expand Down
17 changes: 15 additions & 2 deletions src/api/playbooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,23 @@ import {
mutationToApi,
} from "./utils";

export const getPlaybooks = () => fetchFromApi<Playbook[]>(`/api/playbook/`);
/** SOARCA returns 0001-01-01T00:00:00Z for a validity date that was never set. */
const UNSET_DATE = "0001-01-01";

const dropUnsetDates = (playbook: Playbook): Playbook => {
const next = { ...playbook };
if (next.valid_from?.startsWith(UNSET_DATE)) delete next.valid_from;
if (next.valid_until?.startsWith(UNSET_DATE)) delete next.valid_until;
return next;
};

export const getPlaybooks = () =>
fetchFromApi<Playbook[]>(`/api/playbook/`).then((playbooks) =>
playbooks.map(dropUnsetDates),
);

export const getPlaybookById = (playbookId: string) =>
fetchFromApi<Playbook>(`/api/playbook/${playbookId}`);
fetchFromApi<Playbook>(`/api/playbook/${playbookId}`).then(dropUnsetDates);

export const createPlaybook = (playbook: Partial<Playbook>) =>
mutationToApi<Playbook>(HttpMutationMethod.POST, `/api/playbook/`, playbook);
Expand Down
21 changes: 12 additions & 9 deletions src/components/CodeEditor.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,38 @@ import styled from "styled-components";

const EditorContainer = styled.div`
width: 100%;

margin-bottom: ${({ theme }) => theme.spacing.lg};
`;

const EditorTextarea = styled.textarea<{
$hasError?: boolean;
$minHeight?: string;
}>`
resize: vertical;

width: 100%;
min-height: ${({ $minHeight = "400px" }) => $minHeight};

padding: ${({ theme }) => theme.spacing.md};

border-radius: ${({ theme }) => theme.radius.md};
border: 2px solid
${({ theme, $hasError }) =>
$hasError ? theme.colors.error.border : theme.colors.border.medium};
border-radius: ${({ theme }) => theme.radius.md};

background-color: ${({ theme }) => theme.colors.background.secondary};
color: ${({ theme }) => theme.colors.text.primary};
font: ${({ theme }) => theme.typography.code.font};
color: ${({ theme }) => theme.colors.text.primary};

resize: vertical;
background-color: ${({ theme }) => theme.colors.background.secondary};

&:focus {
outline: none;
border-color: ${({ theme, $hasError }) =>
$hasError ? theme.colors.error.border : theme.colors.info.border};
background-color: ${({ theme }) => theme.colors.background.primary};
outline: none;
}

&:disabled {
opacity: ${({ theme }) => theme.interactions.disabledOpacity};
cursor: not-allowed;
opacity: ${({ theme }) => theme.interactions.disabledOpacity};
}
`;

Expand All @@ -47,6 +45,8 @@ export interface CodeEditorProps extends React.HTMLAttributes<HTMLDivElement> {
disabled?: boolean;
$hasError?: boolean;
$minHeight?: string;
/** Id of the textarea, so a label can point to it. */
$inputId?: string;
}

/**
Expand All @@ -58,6 +58,7 @@ export interface CodeEditorProps extends React.HTMLAttributes<HTMLDivElement> {
* @param disabled - When true the editor is non-editable and shows disabled visuals.
* @param $hasError - When true the editor displays an error border state.
* @param $minHeight - Optional CSS min-height for the editor area (defaults to `400px`).
* @param $inputId - Optional id of the textarea, for a `<label htmlFor>`.
* @example:
* <CodeEditor
* $value={source}
Expand All @@ -72,11 +73,13 @@ export const CodeEditor: React.FC<CodeEditorProps> = ({
disabled,
$hasError,
$minHeight,
$inputId,
...rest
}) => {
return (
<EditorContainer {...rest}>
<EditorTextarea
id={$inputId}
value={$value}
onChange={(e) => $onChange(e.target.value)}
placeholder={placeholder}
Expand Down
2 changes: 2 additions & 0 deletions src/components/Containers.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,11 @@ export const PageContainer = styled.div<PageContainerProps>`
`}
`;

/** Centers its content, such as a loading spinner, in the space it is given. */
export const CenteredCardContent = styled.div`
display: flex;
align-items: center;
justify-content: center;
height: 100%;
min-height: 12rem;
`;
89 changes: 89 additions & 0 deletions src/components/Popover.styles.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
import styled from "styled-components";

export const PopoverTrigger = styled.button<{ $anchorName: string }>`
anchor-name: ${({ $anchorName }) => $anchorName};

display: inline-flex;
align-items: center;
justify-content: center;

padding: ${({ theme }) => `${theme.spacing.sm} ${theme.spacing.md}`};
border-radius: ${({ theme }) => theme.radius.md};

&:hover {
color: ${({ theme }) => theme.colors.info.border};
background: ${({ theme }) => theme.colors.info.bg};
}

&:focus-visible {
outline: 2px solid ${({ theme }) => theme.colors.info.border};
outline-offset: 2px;
}
`;

export const PopoverContent = styled.div<{ $anchorName: string }>`
inset: auto;
position-anchor: ${({ $anchorName }) => $anchorName};
position-area: block-end span-inline-end;
position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline;

inline-size: max-content;
min-inline-size: min(10rem, calc(100vw - 1rem));
max-inline-size: min(18rem, calc(100vw - 1rem));
max-block-size: min(24rem, 90dvh);
margin: ${({ theme }) => theme.spacing.xs};
padding: ${({ theme }) => theme.spacing.xs};
border: 1px solid ${({ theme }) => theme.colors.border.medium};
border-radius: ${({ theme }) => theme.radius.lg};

color: ${({ theme }) => theme.colors.text.primary};

background: ${({ theme }) => theme.colors.background.primary};
box-shadow: ${({ theme }) => theme.shadows.lg};

&:popover-open {
display: flex;
flex-direction: column;
gap: ${({ theme }) => theme.spacing.xs};
}

@media (max-width: 20rem), (max-height: 20rem) {
inset: auto ${({ theme }) => theme.spacing.sm} ${({ theme }) => theme.spacing.sm} auto;
position-area: none;
max-block-size: calc(100dvh - 1rem);
margin: 0;
}
`;

export const PopoverItemButton = styled.button`
display: flex;
flex-shrink: 0;
gap: ${({ theme }) => theme.spacing.sm};
align-items: center;

inline-size: 100%;
padding: ${({ theme }) => `${theme.spacing.sm} ${theme.spacing.md}`};
border-radius: ${({ theme }) => theme.radius.md};

font: ${({ theme }) => theme.typography.caption.font};
color: ${({ theme }) => theme.colors.info.border};
text-align: start;

&:hover:not(:disabled) {
background: color-mix(
in srgb,
${({ theme }) => theme.colors.info.solidBg} ${({ theme }) => theme.interactions.subtleMix},
${({ theme }) => theme.colors.background.primary}
);
}

&:focus-visible {
outline: 2px solid ${({ theme }) => theme.colors.info.border};
outline-offset: -2px;
}

&:disabled {
cursor: not-allowed;
opacity: ${({ theme }) => theme.interactions.disabledOpacity};
}
`;
Loading
Loading