@mitre-attack/attack-data-model/dist/refinements/index.d.ts

A TypeScript API for the MITRE ATT&CK data model

import { z } from 'zod/v4';
import { XMitreDomains } from '../schemas/common/property-schemas/attack-domains.js';
import { Aliases } from '../schemas/common/property-schemas/stix-common-properties.js';
import { ExternalReferences } from '../schemas/common/property-schemas/stix-external-references.js';
import { KillChainPhase } from '../schemas/common/property-schemas/stix-kill-chains.js';
import { XMitreFirstSeenCitation, XMitreLastSeenCitation } from '../schemas/sdo/campaign.schema.js';
import { Technique, XMitreIsSubtechnique, XMitrePermissionsRequired, XMitreEffectivePermissions, XMitreSystemRequirements, XMitreDefenseBypasses, XMitreRemoteSupport, XMitreImpactType, XMitreDataSources, XMitreTacticType } from '../schemas/sdo/technique.schema.js';
import { StixBundle } from '../schemas/sdo/stix-bundle.schema.js';
import 'zod';
import '../schemas/common/property-schemas/attack-id.js';
import '../schemas/common/property-schemas/stix-type.js';
import '../schemas/smo/marking-definition.schema.js';
import '../schemas/sro/relationship.schema.js';
import '../schemas/common/property-schemas/stix-id.js';
import '../schemas/sdo/analytic.schema.js';
import '../schemas/sdo/asset.schema.js';
import '../schemas/sdo/collection.schema.js';
import '../schemas/sdo/data-component.schema.js';
import '../schemas/sdo/data-source.schema.js';
import '../schemas/sdo/detection-strategy.schema.js';
import '../schemas/sdo/group.schema.js';
import '../schemas/sdo/identity.schema.js';
import '../schemas/sdo/malware.schema.js';
import '../schemas/sdo/matrix.schema.js';
import '../schemas/sdo/mitigation.schema.js';
import '../schemas/sdo/tactic.schema.js';
import '../schemas/sdo/tool.schema.js';

/**
 * Creates a refinement for validating that the first alias matches the object's name
 *
 * @returns A refinement callback function for alias validation
 *
 * @remarks
 * This function is used to validate that when aliases are present, the first
 * alias must match the object's name.
 *
 * @example
 * ```typescript
 * const validateFirstAlias = createFirstAliasRefinement();
 * const schema = baseSchema.superRefine(validateFirstAlias);
 * ```
 */
declare function createFirstAliasRefinement(): (ctx: z.core.ParsePayload<{
    aliases?: Aliases;
    name?: string;
}>) => void;
/**
 * Creates a refinement function for validating that the first x_mitre_alias matches the object's name
 *
 * @returns A refinement function for x_mitre_alias validation
 *
 * @remarks
 * This function validates that when x_mitre_aliases are present, the first
 * alias must match the object's name.
 *
 * @example
 * ```typescript
 * const validateFirstXMitreAlias = createFirstXMitreAliasRefinement();
 * const schema = baseSchema.superRefine(validateFirstXMitreAlias);
 * ```
 */
declare function createFirstXMitreAliasRefinement(): (ctx: z.core.ParsePayload<{
    x_mitre_aliases?: string[];
    name?: string;
}>) => void;
/**
 * Creates a refinement for validating citation formats and references
 *
 * @returns A refinement callback function for citation validation
 *
 * @remarks
 * This function validates that citation strings follow the correct format
 * and that all cited sources exist in the external_references.
 *
 * @example
 * ```typescript
 * const validateCitations = createCitationsRefinement();
 * const schema = baseSchema.superRefine(validateCitations);
 * ```
 */
declare function createCitationsRefinement(): (ctx: z.core.ParsePayload<{
    external_references?: ExternalReferences;
    x_mitre_first_seen_citation?: XMitreFirstSeenCitation;
    x_mitre_last_seen_citation?: XMitreLastSeenCitation;
}>) => void;
/**
 * Creates a refinement function for validating x-mitre-collection requirements in a STIX bundle
 *
 * @returns A refinement function for x-mitre-collection validation
 *
 * @remarks
 * This function validates that:
 * 1. The first object in the 'objects' array is of type 'x-mitre-collection'
 * 2. Only one 'x-mitre-collection' object exists in the entire bundle
 *
 * These constraints ensure ATT&CK bundles follow the proper structure with a single collection
 * object serving as the table of contents.
 *
 * @example
 * ```typescript
 * const schema = stixBundleSchema.check(validateXMitreCollection());
 * ```
 */
declare function validateXMitreCollection(): (ctx: z.core.ParsePayload<StixBundle>) => void;
/**
 * Creates a refinement function for validating that objects in an array have no duplicates
 * based on specified keys
 *
 * @param arrayPath - The path to the array property in the context value (e.g., ['objects']). Use [] for direct array validation.
 * @param keys - The keys to use for duplicate detection (e.g., ['id'] or ['source_name', 'external_id']). Use [] for primitive arrays.
 * @param errorMessage - Optional custom error message template. Use {keys} for key values, {value} for primitives, and {index} for position
 * @returns A refinement function for duplicate validation
 *
 * @remarks
 * This function validates that objects in an array are unique based on one or more key fields.
 * It creates a composite key from the specified fields and checks for duplicates.
 *
 * **Supports three validation modes:**
 * 1. Object arrays with single key: `keys = ['id']`
 * 2. Object arrays with composite keys: `keys = ['source_name', 'external_id']`
 * 3. Primitive arrays: `keys = []` (validates the values themselves)
 *
 * @example
 * ```typescript
 * // Single key validation
 * const validateUniqueIds = validateNoDuplicates(['objects'], ['id']);
 * const schema = baseSchema.check(validateUniqueIds);
 *
 * // Composite key validation
 * const validateUniqueRefs = validateNoDuplicates(
 *   ['external_references'],
 *   ['source_name', 'external_id'],
 *   'Duplicate reference found with source_name="{source_name}" and external_id="{external_id}"'
 * );
 *
 * // Primitive array validation (e.g., array of strings)
 * const validateUniqueStrings = validateNoDuplicates(
 *   [],
 *   [],
 *   'Duplicate value "{value}" found'
 * );
 * ```
 */
declare function validateNoDuplicates(arrayPath: string[], keys: string[], errorMessage?: string): (ctx: z.core.ParsePayload<unknown>) => void;
/**
 * Creates a refinement function for validating that all STIX IDs referenced in x_mitre_contents
 * exist in the bundle's objects array
 *
 * @returns A refinement function for x_mitre_contents reference validation
 *
 * @remarks
 * This function validates that every STIX ID referenced in the collection's x_mitre_contents
 * property (which acts as a table of contents for the bundle) has a corresponding object
 * in the bundle's objects array. This ensures referential integrity within the bundle.
 *
 * The function expects:
 * - The first object in the bundle to be a Collection (x-mitre-collection type)
 * - Each object_ref in x_mitre_contents to match an id in the objects array
 *
 * @example
 * ```typescript
 * const schema = stixBundleSchema.check(validateXMitreContentsReferences());
 * ```
 */
declare function validateXMitreContentsReferences(): (ctx: z.core.ParsePayload<StixBundle>) => void;
/**
 * Creates a refinement function for validating ATT&CK ID in external references
 *
 * @returns A refinement function for ATT&CK ID validation
 */
declare function createAttackIdInExternalReferencesRefinement(): (ctx: z.core.ParsePayload<Technique | {
    external_references?: ExternalReferences;
    x_mitre_is_subtechnique?: XMitreIsSubtechnique;
}>) => void;
/**
 * Creates a refinement function for validating enterprise-only properties of techniques
 *
 * @returns A refinement function for enterprise-only property validation
 */
declare function createEnterpriseOnlyPropertiesRefinement(): (ctx: z.core.ParsePayload<Technique | {
    x_mitre_domains?: XMitreDomains;
    kill_chain_phases?: KillChainPhase[];
    x_mitre_permissions_required?: XMitrePermissionsRequired;
    x_mitre_effective_permissions?: XMitreEffectivePermissions;
    x_mitre_system_requirements?: XMitreSystemRequirements;
    x_mitre_defense_bypassed?: XMitreDefenseBypasses;
    x_mitre_remote_support?: XMitreRemoteSupport;
    x_mitre_impact_type?: XMitreImpactType;
    x_mitre_data_sources?: XMitreDataSources;
}>) => void;
/**
 * Creates a refinement function for validating mobile-only properties of techniques
 *
 * @returns A refinement function for mobile-only property validation
 */
declare function createMobileOnlyPropertiesRefinement(): (ctx: z.core.ParsePayload<Technique | {
    x_mitre_domains?: XMitreDomains;
    x_mitre_tactic_type?: XMitreTacticType;
    x_mitre_data_sources?: XMitreDataSources;
}>) => void;

export { createAttackIdInExternalReferencesRefinement, createCitationsRefinement, createEnterpriseOnlyPropertiesRefinement, createFirstAliasRefinement, createFirstXMitreAliasRefinement, createMobileOnlyPropertiesRefinement, validateNoDuplicates, validateXMitreCollection, validateXMitreContentsReferences };