frontend

Imported from anilyagiz/autosecops-x (frontend/AGENTS.md). Install upstream with npx skills add anilyagiz/autosecops-x --skill frontend. Copyright stays with the author.

Frontend AGENTS.md

Overview

The AutoSecOps frontend is a single-page React/TypeScript application built from frontend/index.jsx and bundled with Webpack 5. It serves the analyst and admin UI for the AutoSecOps control plane.

• Stack: React 18.3.1, React DOM 18.3.1, TypeScript 5.8.2, React Router 3.2.6, react-query 3.39.3, axios 1.18.0, SCSS, Webpack 5.98.0.
• Runtime: served from frontend/templates/react.ejs, built into assets/.
• State: React Context for global app/user state plus react-query for server state.
• Tooling: Jest 29.2.0, MSW 2.5.1, React Testing Library, Storybook 8.4.7, ESLint 7.32.0 (Airbnb + TypeScript + Prettier).

Build & Run

Use yarn from the repository root. Do not run npm install in the root (it creates a package-lock.json which is gitignored).

Architecture

• Entry point: frontend/index.jsx (Webpack entry: webpack.config.js:56).
• Routing: React Router v3, declared in frontend/router/index.tsx and split into route components in frontend/router/components/. Path constants live in frontend/router/paths.ts and frontend/router/url_prefix.ts.
• Layouts: frontend/layouts/CoreLayout/CoreLayout.tsx, frontend/layouts/GatedLayout/GatedLayout.tsx, frontend/layouts/UnsupportedScreenSize/UnsupportedScreenSize.tsx.
• State: frontend/context/app.tsx manages user, team, and config; frontend/context/notification.tsx for flash messages; frontend/context/query.tsx, frontend/context/policy.tsx, frontend/context/table.tsx, frontend/context/routing.tsx for focused cross-cutting state.
• API: frontend/services/index.ts exports the core axios send helpers (sendRequest, sendRequestWithProgress, sendRequestWithHeaders, sendRequestWithProgressAndHeaders). Domain-specific endpoints live in frontend/services/entities/*.ts.
• Styling: SCSS with global variables and helpers in frontend/styles/var/, frontend/styles/global/, and per-component _styles.scss files.

Directory Structure

Key Components

Notable reusable component areas (co-located pattern: component + _styles.scss + *.tests.tsx + index.ts):

• Data tables: components/TableContainer/DataTable/* (specialized cells, filters, action buttons, status cells, setup cells, performance cells).
• Modals / banners: components/Modal/, components/ModalFooter/, components/InfoBanner/, components/FlashMessage/, components/MainContent/, components/Sandbox/, components/GitOpsModeTooltipWrapper/.
• Activity and feeds: components/ActivityTimeline/, components/ActivityItem/, components/ActivityDetails/InstallDetails/, components/FeedListItem/.
• Hosts / MDM / platform: components/AddHostsModal/, components/HostIsolation/, components/MDM/*, components/PlatformSelector/, components/PlatformCompatibility/, components/LastUpdatedHostCount/.
• Forms / editors: components/SQLEditor/, components/Editor/, components/FileUploader/, components/Icon/, components/Spinner/, components/DataError/, components/EmptyTable/, components/StatusIndicator/.
• Icons: components/Icon/ with icon definitions; add SVGs in components/icons/ then register in ICON_MAP.

Key Pages

Pages are co-located under frontend/pages/ and grouped by product surface:

• Dashboard: pages/DashboardPage/ with cards (activity feed, host counts, OS, MDM, Munki, software, missing hosts, predictive risk, etc.).
• Hosts / Devices: pages/hosts/ManageHostsPage/, pages/hosts/details/HostDetailsPage/, pages/hosts/details/DeviceUserPage/, pages/hosts/details/HostQueryReport/.
• Queries / Live: pages/queries/ManageQueriesPage/, pages/queries/details/QueryDetailsPage/, pages/queries/live/LiveQueryPage/, pages/queries/edit/EditQueryPage/, pages/packs/.
• Policies / Controls: pages/policies/, pages/ManageControlsPage/ (OS updates, OS settings, scripts, secrets, setup experience).
• Software: pages/SoftwarePage/ (titles, OS, vulnerabilities, add, custom package, app store, maintained apps, version/ title details).
• Security Operations: pages/SecurityOperationsPage/, pages/SecurityOperations/ (incidents, cases), pages/EvidenceCenterPage/, pages/ThreatHuntingPage/, pages/SigmaRulesPage/, pages/PlaybookDesignerPage/, pages/MitreCoveragePage/, pages/case/.
• Agentic / AI: pages/AgentCommandCenterPage/, pages/DashboardPage/cards/ActivityFeed/components/ActivityAutomationDetailsModal/.
• Admin: pages/admin/OrgSettingsPage/, pages/admin/IntegrationsPage/, pages/admin/UserManagementPage/, pages/admin/TeamManagementPage/.
• Auth / User: pages/LoginPage/, pages/RegistrationPage/, pages/ForgotPasswordPage/, pages/ResetPasswordPage/, pages/ConfirmInvitePage/, pages/ConfirmSSOInvitePage/, pages/MfaPage/, pages/LogoutPage/, pages/AccountPage/, pages/ApiOnlyUser/.
• Errors: pages/errors/AutoSecOps403/, pages/errors/AutoSecOps404/.

Services and API Calling

• Core HTTP: frontend/services/index.ts defines sendRequest, sendRequestWithProgress, sendRequestWithHeaders, and sendRequestWithProgressAndHeaders. All attach the Authorization: Bearer <token> header and prefix /api.
• Entity modules: frontend/services/entities/*.ts (e.g. hosts.ts, queries.ts, users.ts, software.ts, mdm.ts, incidents.ts, cases.ts, sigma_rules.ts, playbooks.ts, threat_hunting.ts, agentic_control_plane.ts, etc.).
• Calling patterns:
  • Use useQuery/useMutation from react-query when loading on mount or caching is needed.
  • Use direct async/await calls for one-off user actions.
  • Keep getErrorMessage helpers in sibling helpers.ts or helpers.tsx files to keep components clean.

Type System

• Global interfaces: frontend/interfaces/*.ts are shared I-prefixed types (IHost, IUser, IConfig, ITeam, IQuery, etc.).
• Local interfaces: Define local prop/state interfaces inside the consuming component/page file.
• TypeScript config: tsconfig.all_frontend.json extends @tsconfig/recommended and sets baseUrl to frontend so imports can be un-prefixed (e.g. import App from "components/App").

Patterns

• Co-located files: ComponentName.tsx, _styles.scss, ComponentName.tests.tsx, index.ts in one directory.
• Named exports for utilities: export const helper = .... Do not export default utility objects.
• I-prefixed global interfaces: IHost, IUser, IConfig.
• Functional components and hooks: use functional components, not classes.
• State: prefer useState. Prop drill no more than ~2 levels; otherwise use Context.
• API data: read config from Context; update config by re-fetching from the API.
• react-query: type generics as useQuery<IResponse, Error, IData> and use select when the rendered data shape differs.
• Forms: wrap with native <form> and onSubmit={handleSubmit} where handleSubmit(evt: React.FormEvent<HTMLFormElement>) calls evt.preventDefault() and returns early if validate(formData) returns errors.
• Validation: pure validate(formData) functions return Record<string, string> mapping field names to error messages. Set new errors on blur and only update existing errors on change.
• Page layout: top-level pages use MainContent and SidePanelContent / SidePanelPage.
• Handlers: prefer handler prop names like onSubmit and onUpdateSomething. Avoid prop-spread syntax.
• Navigation/flash: call router.push(path) before renderFlash or the flash may auto-hide on the route change. Use persistOnPageChange: true in renderFlash options when needed.
• Errors: keep error message formatting in helpers.ts / helpers.tsx (getErrorMessage).
• Modals: wrap action buttons in modal-cta-wrap.
• Icons: add optimized SVG components in components/icons/, then register the name in ICON_MAP.
• Security: avoid dangerouslySetInnerHTML. If unavoidable, run user input through DOMPurify.sanitize.
• File size: aim for <500 lines per file; split larger components/pages.

Testing

• Unit / integration: Jest 29.2.0 with jest-fixed-jsdom, config at frontend/test/jest.config.js, setup at frontend/test/test-setup.ts.
• Test match: frontend/**/*tests.[jt]s?(x). Tests are co-located with the component.
• Mocking: MSW default handlers in frontend/test/handlers/ and frontend/test/default-handlers.ts; mock server defined in frontend/test/mock-server.ts.
• Stubs: frontend/__mocks__/*Mock.ts files provide typed default mocks with override helpers.
• E2E: Playwright via yarn test:e2e and yarn test:e2e:ui.

Anti-Patterns

• Do not use class components.
• Do not use Redux.
• Do not use default exports for utility objects.
• Do not reach for @ts-ignore, @ts-expect-error, or as any to silence types.
• Do not spread props onto components (<Component {...props} />).
• Do not use dangerouslySetInnerHTML without sanitizing first.
• Do not run npm install in the repository root (use yarn / make deps-js).

Boundaries and Critical Rules

• Work only inside frontend/ unless the task explicitly extends to other directories.
• ee/ may be edited when relevant after reading ee/AGENTS.md; do not edit website/ or portal/ unless explicitly authorized.
• The root project uses yarn. Never run npm install in the repository root.
• Do not make unsupported commercial claims in any docs or UI copy; see root AGENTS.md / make verify-claims.
• Prefer functional components + hooks. Keep global interfaces I-prefixed and in frontend/interfaces/.
• Use react-query for server state, Context for cross-cutting UI/app state.
• Respect the co-location pattern; tests and styles live next to the component/page they cover.