ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
import type {
ApiKeyCreateResponse,
ApiKeyMeta,
AttackPathsResponse,
Campaign,
CampaignGraph,
ExecutionChain,
FeasibilityResponse,
Finding,
LiveExecutionResponse,
LiveSubmissionOptions,
ModuleMeta,
MonthlyFindingStats,
ReportItem,
TemplateMeta,
TemplatePlanResult,
TokenResponse,
UserProfile,
VaultRestoreResult,
WebSocketTicketResponse
} from "./types";
import {
apiBlobRequest,
apiRequest,
ApiError,
bootstrapBrowserCsrf,
browserMutationRequest,
withRefreshCookieLock
} from "./http";
import { beginIdentityTransition, installSessionIfCurrent } from "./session";
const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
const pendingLiveSubmissions = new Map<string, string>();
function canonicalJson(value: unknown): string {
if (Array.isArray(value)) {
return `[${value.map(canonicalJson).join(",")}]`;
}
if (typeof value === "object" && value !== null) {
return `{${Object.entries(value)
.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
.join(",")}}`;
}
return JSON.stringify(value) ?? "null";
}
function liveSubmissionFingerprint(path: string, body: Record<string, unknown>): string {
return `${path}\u0000${canonicalJson(body)}`;
}
function canonicalIdempotencyKey(value: string): string {
if (!UUID_V4.test(value)) {
throw new ApiError(422, "Idempotency-Key must be a canonical lowercase UUIDv4");
}
return value;
}
function createIdempotencyKey(): string {
const value = globalThis.crypto?.randomUUID?.();
if (typeof value !== "string") {
throw new ApiError(503, "Secure UUID generation unavailable");
}
return canonicalIdempotencyKey(value);
}
function attachIdempotencyKey(error: unknown, key: string): never {
if ((typeof error === "object" && error !== null) || typeof error === "function") {
Object.defineProperty(error, "idempotencyKey", {
configurable: false,
enumerable: true,
value: key,
writable: false
});
}
throw error;
}
async function liveExecutionRequest(
path: string,
body: Record<string, unknown>,
options: LiveSubmissionOptions = {}
): Promise<LiveExecutionResponse> {
const fingerprint = liveSubmissionFingerprint(path, body);
if (options.startNewSubmission) {
pendingLiveSubmissions.delete(fingerprint);
}
const supplied = options.idempotencyKey === undefined
? undefined
: canonicalIdempotencyKey(options.idempotencyKey);
const key = supplied ?? pendingLiveSubmissions.get(fingerprint) ?? createIdempotencyKey();
pendingLiveSubmissions.set(fingerprint, key);
try {
const result = await apiRequest<Record<string, unknown>>(path, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Idempotency-Key": key
},
body: JSON.stringify(body)
});
if (pendingLiveSubmissions.get(fingerprint) === key) {
pendingLiveSubmissions.delete(fingerprint);
}
return { ...result, idempotency_key: key };
} catch (error) {
attachIdempotencyKey(error, key);
}
}
function clearPendingLiveSubmissions(): void {
pendingLiveSubmissions.clear();
}
export async function login(username: string, password: string): Promise<TokenResponse> {
clearPendingLiveSubmissions();
const loginSession = beginIdentityTransition();
const token = await withRefreshCookieLock(async () => {
await bootstrapBrowserCsrf();
await browserMutationRequest<null>("/auth/logout");
await bootstrapBrowserCsrf();
const body = new URLSearchParams();
body.set("username", username);
body.set("password", password);
return browserMutationRequest<TokenResponse>("/auth/token", {
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body
});
});
if (!installSessionIfCurrent(
loginSession,
token.access_token,
token.session_coordination_key,
token.refresh_generation
)) {
throw new ApiError(401, "Session changed");
}
return token;
}
export interface SsoInitiationResponse {
configured: boolean;
protocol: "saml" | "oidc";
redirect_url: string;
flow_id: string;
}
export async function initiateSso(orgSlug: string = "default"): Promise<SsoInitiationResponse> {
const query = new URLSearchParams({ org: orgSlug });
return apiRequest<SsoInitiationResponse>(`/auth/sso/init?${query.toString()}`, {
method: "GET"
});
}
export async function logout(): Promise<void> {
clearPendingLiveSubmissions();
await withRefreshCookieLock(async () => {
await browserMutationRequest<null>("/auth/logout");
});
}
export async function logoutAll(): Promise<void> {
clearPendingLiveSubmissions();
await withRefreshCookieLock(async () => {
await browserMutationRequest<null>("/auth/logout-all", {}, { authenticated: true });
});
}
export function campaignEventsPath(campaignId: string, ticket: string): string {
return `/ws/campaigns/${encodeURIComponent(campaignId)}/events?ticket=${encodeURIComponent(ticket)}`;
}
export function buildModuleRunPayload(
campaignId: string,
params: Record<string, unknown>,
dryRun = true
): { campaign_id: string; params: Record<string, unknown>; dry_run: boolean } {
return { campaign_id: campaignId, params, dry_run: dryRun };
}
export const api = {
me: () => apiRequest<UserProfile>("/auth/me"),
health: () => apiRequest<Record<string, unknown>>("/health"),
telemetry: (campaignId?: string | unknown) =>
apiRequest<Record<string, unknown>>(typeof campaignId === "string" && campaignId ? `/telemetry?campaign_id=${encodeURIComponent(campaignId)}` : "/telemetry"),
monthlyStats: (campaignId?: string | unknown) =>
apiRequest<MonthlyFindingStats>(typeof campaignId === "string" && campaignId ? `/stats/monthly?campaign_id=${encodeURIComponent(campaignId)}` : "/stats/monthly"),
campaigns: () => apiRequest<Campaign[]>("/campaigns"),
createCampaign: (body: { name: string; client: string; targets: string[]; scope_cidrs: string[]; noise_profile: string }) =>
apiRequest<Campaign>("/campaigns", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body)
}),
campaign: (id: string) => apiRequest<Campaign>(`/campaigns/${encodeURIComponent(id)}`),
websocketTicket: (id: string) =>
apiRequest<WebSocketTicketResponse>(
`/campaigns/${encodeURIComponent(id)}/websocket-ticket`,
{ method: "POST" }
),
deleteCampaign: (id: string) =>
apiRequest<Record<string, string>>(`/campaigns/${encodeURIComponent(id)}`, { method: "DELETE" }),
findings: (id: string) => apiRequest<Finding[]>(`/campaigns/${encodeURIComponent(id)}/findings`),
cvss: (id: string) => apiRequest<Record<string, unknown>>(`/campaigns/${encodeURIComponent(id)}/cvss`),
restoreVault: (id: string) =>
apiRequest<VaultRestoreResult>(`/campaigns/${encodeURIComponent(id)}/restore-vault`, { method: "POST" }),
runCampaign: (
id: string,
body: Record<string, unknown>,
options: LiveSubmissionOptions = {}
): Promise<TemplatePlanResult | LiveExecutionResponse> => {
const path = `/campaigns/${encodeURIComponent(id)}/run`;
return body.dry_run === true
? apiRequest<TemplatePlanResult>(path, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body)
})
: liveExecutionRequest(path, body, options);
},
diffCampaign: (id: string, otherId: string) =>
apiRequest<Record<string, unknown>>(
`/campaigns/${encodeURIComponent(id)}/diff/${encodeURIComponent(otherId)}`
),
modules: () => apiRequest<ModuleMeta[]>("/modules"),
executionChains: () => apiRequest<ExecutionChain[]>("/modules/execution-chains"),
runModule: (
moduleId: string,
payload: ReturnType<typeof buildModuleRunPayload>,
options: LiveSubmissionOptions = {}
) => {
const path = `/modules/${encodeURIComponent(moduleId)}/run`;
return payload.dry_run
? apiRequest<Record<string, unknown>>(path, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload)
})
: liveExecutionRequest(path, payload, options);
},
moduleFeasibility: (
moduleId: string,
body: { campaign_id: string; params?: Record<string, unknown>; target?: string }
) =>
apiRequest<FeasibilityResponse>(`/modules/${encodeURIComponent(moduleId)}/feasibility`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body)
}),
generateReport: (campaignId: string, format: string) =>
apiRequest<Record<string, string>>(
`/reports/${encodeURIComponent(campaignId)}?fmt=${encodeURIComponent(format)}`,
{ method: "POST" }
),
reports: (campaignId: string) =>
apiRequest<{ campaign_id: string; reports: ReportItem[] }>(`/reports/${encodeURIComponent(campaignId)}`),
reportDownloadUrl: (campaignId: string, filename: string) =>
`/reports/${encodeURIComponent(campaignId)}/files/${encodeURIComponent(filename)}`,
downloadReport: (campaignId: string, filename: string) =>
apiBlobRequest(`/reports/${encodeURIComponent(campaignId)}/files/${encodeURIComponent(filename)}`),
deleteReport: (campaignId: string, filename: string) =>
apiRequest<Record<string, string>>(
`/reports/${encodeURIComponent(campaignId)}/files/${encodeURIComponent(filename)}`,
{ method: "DELETE" }
),
clearReports: (campaignId: string) =>
apiRequest<{ status: string; campaign_id: string; deleted: number }>(
`/reports/${encodeURIComponent(campaignId)}`,
{ method: "DELETE" }
),
graph: (campaignId: string) => apiRequest<CampaignGraph>(`/graph/${encodeURIComponent(campaignId)}`),
attackPaths: (campaignId: string) =>
apiRequest<AttackPathsResponse>(`/graph/${encodeURIComponent(campaignId)}/attack-paths`),
ingestBloodhound: (campaignId: string, jsonPath: string) =>
apiRequest<Record<string, unknown>>(`/graph/${encodeURIComponent(campaignId)}/bloodhound`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ json_path: jsonPath })
}),
templates: () => apiRequest<TemplateMeta[]>("/templates"),
templatePlan: (name: string, globalParams: Record<string, unknown>) =>
apiRequest<Record<string, unknown>>(`/templates/${encodeURIComponent(name)}/plan`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ global_params: globalParams })
}),
activeStrategy: () => apiRequest<Record<string, unknown>>("/strategy/active"),
engageStrategy: (
body: Record<string, unknown>,
options: LiveSubmissionOptions = {}
) => liveExecutionRequest("/strategy/engage", body, options),
changePassword: (body: { current_password: string; new_password: string }) =>
apiRequest<Record<string, string>>("/auth/change-password", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body)
}),
apiKeys: () => apiRequest<ApiKeyMeta[]>("/auth/api-keys"),
createApiKey: (body: { name: string; scopes: string; expires_days?: number }) =>
apiRequest<ApiKeyCreateResponse>("/auth/api-keys", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body)
}),
deleteApiKey: (id: string) => apiRequest<Record<string, string>>(`/auth/api-keys/${encodeURIComponent(id)}`, {
method: "DELETE"
}),
securityAudit: () => apiRequest<Record<string, unknown>>("/security/audit"),
users: () => apiRequest<Record<string, unknown>[]>("/security/users"),
edrStats: () => apiRequest<Record<string, unknown>>("/edr/bypass/stats"),
reportBypass: (body: Record<string, unknown>) =>
apiRequest<Record<string, unknown>>("/edr/bypass/report", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body)
})
};