@crowdstrike/foundry-js
foundry.js
javascript library provides convenient access to the CrowdStrike's Foundry API to author UI pages and extensions.
Installation
npm install @crowdstrike/foundry-js
yarn add @crowdstrike/foundry-js
pnpm add @crowdstrike/foundry-js
Overview 🔎
SDK provides abstractions to build Foundry Pages, Extensions and interact with Foundry artifacts - Workflows, Collections, LogScale, API Integrations and CrowdStrike APIs.
Usage
When application starts, it should establish connection to Falcon Console. If connection is not establishes in first 5 seconds - app or extension will be dropped from loading on the page.
import FalconApi from '@crowdstrike/foundry-js';
(async () => {
const falcon = new FalconApi();
await falcon.connect();
});
Receive events from Falcon Console
When UI extensions is loaded, it might receive data for the context it is loaded,
for example if UI extension was built for Detection side panel, it will receive detection associated data.
If data
is updated in Falcon Console - event will automatically execute and pass new data.
(async () => {
falcon.events.on('data', (data) => {
});
});
Working with Workflows
To call on-demand workflow:
(async () => {
const config = { name: 'WorkflowName', depth: 0 };
const pendingResult = await falcon.api.workflows.postEntitiesExecuteV1({}, config);
const result = await falcon.api.workflows.getEntitiesExecutionResultsV1({ ids: triggerResult.resources[0] });
});
Working with Collections
(async () => {
const sampleData = {
"name": "John",
"age": 42,
"aliases": ["Doe", "Foundry"]
};
const collection = falcon
.collection({collection: '<collectionName>' });
const result = await collection.write('test-key', sampleData);
const record = await collection.read('test-key');
const searchResult = await collection.search({ filter: `name:'*'` });
const deleteResponse = await collection.delete('test-key');
});
Working with LogScale
(async () => {
const writeResult = await falcon.logscale.write({ test: 'check' });
const queryResult = await falcon.logscale.query({ search_query: "*", start: "1h" });
const savedQueryResult = await falcon.logscale.savedQuery({ id: "<savedQueryId>", start: "30d", mode: 'sync' });
});
Working with API Integration
To call API Integration, App should be initially provisioned, and configuration for API Integration should be set up.
(async () => {
const apiIntegration = falcon.apiIntegration({
operationId: 'Get Cities',
});
const response = await apiIntegration.execute({
request: {
params: {
path: {
country: 'Spain'
}
}
}
});
});
Working with Cloud Functions
(async () => {
const config = {
name: 'CloudFunctionName',
version: 1
};
const cloudFunction = falcon.cloudFunction(config);
const getResponse = await cloudFunction.path('/?id=150&mode=compact')
.get();
const postResponse = await cloudFunction.path('/')
.post({ name: 'test' });
const patchResponse = cloudFunction.path('/')
.patch({ name: 'test' });
const putResponse = cloudFunction.path('/')
.put({ name: 'test' });
const deleteResponse = cloudFunction.path('/?id=100')
.delete();
});
Navigation utilities
As Page or UI extension will run inside sandboxed iframe, clicking links or navigating will be limited.
When browser URL changes, Foundry UI Page will receive that data via iframe hash change event.
You can listen to hash change event and process your app internal navigation.
window.addEventListener("hashchange", (event) => {
let rawHash = new URL(event.newURL).hash;
const path = rawHash.substring(1);
}, false);
const initialPath = document.location.hash.substring(1);
If you have links in your application, that point to the internal URLs of your application (for example navigation from /page-1 to /page-2) -
you can add data-
attribute to those links, and add onClick handler, that will handle navigation outside of iframe and will update iframe hash.
document.querySelector('[data-internal-link]')
.addEventListener('click', (event) => falcon.navigation.onClick(event, '_self', 'internal'));
If you have external links that you want to navigate to, for example www.crowdstrike.com, you can add data-
attribute to identify those:
document.querySelector('[data-external-link]')
.addEventListener('click', (event) => falcon.navigation.onClick(event));
Modal utility
To open a modal within Falcon Console, rendering UI extension of your choice:
const result = await api.ui.openModal(
{
id: '<extension ID as defined in the manifest>',
type: 'extension'
},
'Modal title',
{
path: '/',
data: { foo: 'bar' },
size: 'lg',
align: 'top',
}
);
await api.ui.closeModal();
await api.ui.closeModal({ foo: 'bar' });
Sample apps
Additionally