@pulumi/compliance-policy-manager/index.d.ts

This repository contains a growing set of Compliance Policies to validate your infrastructure using Pulumi's Crossguard Policy-as-Code framework.

export * from "./version";
import * as policy from "@pulumi/policy";
export { loadPlugins } from "./plugin";
/**
 * Represents the arguments for selecting policies.
 */
export interface FilterPolicyArgs {
    /**
     * An array of vendor names to select policies by.
     */
    vendors?: string[];
    /**
     * An array of service names to select policies by.
     */
    services?: string[];
    /**
     * An array of compliance framework names to select policies by.
     */
    frameworks?: string[];
    /**
     * An array of severity levels to select policies by.
     */
    severities?: string[];
    /**
     * An array of topics to select policies by.
     */
    topics?: string[];
}
/**
 * Represents the arguments for displaying policy selection statistics.
 */
export interface DisplaySelectionStatsArgs {
    /**
     * If set to `true`, displays general statistics about the number of registered policies, how many have been selected and how many remain in the pool.
     */
    displayGeneralStats: boolean;
    /**
     * If `true` then shows information about included policy modules and their version.
     */
    displayModuleInformation?: boolean;
    /**
     * If `true` then shows the name of the policies that have been included in the Policy Pack at runtime and the associated enforcement level.
     */
    displaySelectedPolicyNames?: boolean;
}
/**
 * Metadata associated with a policy.
 */
export interface PolicyMetadata {
    /**
     * An array of vendor names associated with the policy.
     */
    vendors?: string[];
    /**
     * An array of service names associated with the policy.
     */
    services?: string[];
    /**
     * An array of compliance framework names associated with the policy.
     */
    frameworks?: string[];
    /**
     * The severity level of the policy.
     */
    severity?: string;
    /**
     * An array of topics related to the policy.
     */
    topics?: string[];
}
/**
 * Represents the arguments for registering a policy.
 */
export interface RegisterPolicyArgs extends PolicyMetadata {
    /**
     * The resource validation policy to be associated with the registered policy.
     */
    resourceValidationPolicy: policy.ResourceValidationPolicy;
}
/**
 * Represents information about a policy.
 */
export interface PolicyInfo {
    /**
     * The name of the policy.
     */
    policyName: string;
    /**
     * The resource validation policy associated with the policy.
     */
    resourceValidationPolicy: policy.ResourceValidationPolicy;
    /**
     * Metadata associated with the policy.
     */
    policyMetadata: PolicyMetadata;
}
/**
 * Represents information about a policy package.
 */
export interface ModuleInfo {
    /**
     * The name of the policy package.
     */
    name: string;
    /**
     * The version of the policy package.
     */
    version: string;
}
/**
 * This interface represents general Compliance policy usage information.
 */
export interface PolicyManagerStats {
    /**
     * The value of `policyCount` represents the total number of registered policies.
     */
    policyCount: number;
    /**
     * The value of `remainingPolicyCount` represents the number of policies available for selection.
     * You may call `resetPolicyfilter()` to reset the selection filter, however, be aware that you may get duplicated policies.
     */
    remainingPolicyCount: number;
    /**
     * The value of `selectedPoliciesCount` represents the number of policies that have already been provider by `selectPolicies()`.
     */
    selectedPoliciesCount: number;
    /**
     * `selectedPolicies` contains all the polcy that have been selected. Calling `resetPolicySelector()` will empty this list.
     */
    selectedPolicies: policy.ResourceValidationPolicy[];
    /**
     * `registeredModules` contains information about policy modules that have registered themselves.
     */
    registeredModules: ModuleInfo[];
}
/**
 * The matching TypeScript `interface` for `PolicyManager.policyConfigSchema` used to retrieve the policy configuration.
 */
export interface PolicyConfigSchemaArgs {
    /**
     * An array of string containing resource names or regular expressions used to determine if a resource should be excluded from the policy evaluation.
     */
    excludeFor?: string[];
    /**
     * An array of string containing resource names or regular expressions used to determine if a resource must be included from the policy evaluation.
     */
    includeFor?: string[];
    /**
     * When set to `true`, perform case-insensitive searches. `false` makes the searches case-sensitive.
     */
    ignoreCase?: boolean;
    /**
     * When enabled (`true`), Policy Manager will emit a message to indicate which resource was excluded from policy evaluation.
     * If undefined or set to `false`, the resource evaluation is skipped silently.
     */
    logExcludedResources?: boolean;
}
/**
 * Class to manage policies.
 */
export declare class PolicyManager {
    /**
     * An array containing all registered policies.
     */
    private readonly allPolicies;
    /**
     * An array containing all registered policy names. This is used to
     * prevent duplicated names since the Pulumi service requires a
     * unique name for each policy.
     */
    private readonly allNames;
    /**
     * A `Record` that contains policies arranged per vendor.
     */
    private readonly vendors;
    /**
     * A `Record` that contains policies arranged per service.
     */
    private readonly services;
    /**
     * A `Record` that contains policies arranged per framework.
     */
    private readonly frameworks;
    /**
     * A `Record` that contains policies arranged per topic.
     */
    private readonly topics;
    /**
     * A `Record` that contains policies arranged per severity.
     */
    private readonly severities;
    /**
     * An array of registered policies that haven't been returned yet via `selectPolicies()`.
     * This is needed to ensure users get policies only once so the Pulumi service doesn't
     * complain about duplicated policies.
     */
    private remainingPolicies;
    /**
     * An array of policy names that have been returned via `selectPolicies()`.
     * This is used to return by `getStats()` so it's possible to know the list
     * of policies that have been selected.
     */
    private selectedPolicies;
    /**
     * An array containing the list of registered modules.
     */
    private registeredModules;
    /**
     * A Pulumi managed policy configuration schema. This policy schema, when associated
     * to a policy, offers a basic policy configuration scheme, which in turn can be
     * leveraged inside the policy itself.
     *
     * See `shouldEvalPolicy()` for more information.
     */
    readonly policyConfigSchema: policy.PolicyConfigSchema;
    /**
     * This function determines if a policy should be evaluated for the given resource based on the
     * Policy configuration. The user supplied list of matching names provided via the Policy
     * Configuration is checked against the resource name.
     *
     * This function checks first for explicit inclusions, then for explicit exclusions and finally
     * returns `true` if no matches occured.
     *
     * Note: This functon is primarily intented to be used within a policy.
     *
     * @param args The argument `ResourceValidationArgs` provided during the policy evaluation.
     * @returns `true` if the policy should be evaluated for the given resource, `false` otherwise.
     */
    shouldEvalPolicy(args: policy.ResourceValidationArgs): boolean;
    /**
     * The function `getSelectionStats()` returns statistics about the number of registered
     * policies as well as the names and count of already selected policies and the number
     * of policies that haven't been selected yet.
     *
     * @returns Returns a populated `PolicyManagerStats`.
     */
    getSelectionStats(): PolicyManagerStats;
    /**
     * This function `displaySelectionStats()` displays general statistics about policies
     * that have been returned by `selectPolicies()` and how many remain in the pool.
     * Additional information about registered policy modules are displayed too.
     *
     * @returns No value is returned.
     */
    displaySelectionStats(args: DisplaySelectionStatsArgs): void;
    /**
     * When executing the policy selector, it's crucial for the function to return each policy
     * exactly once. This ensures that the Pulumi service doesn't return an error related to
     * duplicated policies when a Policy Pack is published.
     *
     * The purpose of this function is to reset the policy filter, enabling a fresh start.
     * Consequently, when you invoke `selectPolicies()`, it will take into account all the
     * registered policies including the ones previously selected. This may add previously
     * selected policies to your Policy Pack.
     *
     * This function for unit tests purpose and most users/developers shouldn't use it.
     */
    resetPolicySelector(): void;
    /**
     * This function returns a resource policy information by providing the policy
     * name.
     *
     * This function for unit tests purpose and most users/developers shouldn't use it.
     *
     * **Note**: The returned policy is not removed from the pool of available policies.
     * If you want to select an individual policy, then you should be using
     * `selectPolicyByName()` instead.
     *
     * @param name The policy name to search for and return.
     * @returns The PolicyInfo if found, otherwise `undefined`.
     */
    getPolicyByName(name: string): PolicyInfo | undefined;
    /**
     * This function searches for a policy based on the provided `name`. If the
     * policy is found, then it is removed from the pool of available policies
     * and the policy is returned. If not found, the `undefined` is returned.
     *
     * @param name The policy name to search for and return.
     * @param enforcementLevel The desired policy enforcement Level. Valid values are `advisory`, `mandatory` and `disabled`.
     * @returns A `ResourceValidationPolicy` policy that matched the supplied `name` or `undefined` if the policy wasn't found in the pool of `remainingPolicies`.
     */
    selectPolicyByName(name: string, enforcementLevel?: string): policy.ResourceValidationPolicy | undefined;
    /**
     * Takes an array of policy names and set the desired enforcement level on each policy.
     * If a provided policy name has alread been selected, then the matching policy is not
     * returned as part of the result.
     *
     * @param names An array of policy names.
     * @param enforcementLevel The desired enforcement level for those policies.
     * @returns An array of policies.
     */
    selectPoliciesByName(names: string[], enforcementLevel: string): policy.ResourceValidationPolicy[];
    /**
     * Select policies based on criterias provided as arguments. The selectiopn filter only
     * returns policies that match selection criterias. Effectively, this function performs
     * an `or` operation within each selection criteria, and an `and` operation between
     * selection criterias.
     *
     * You may also provide an array of cherry-picked polcies. The function takes care of
     * removing duplicates as well as ignoring already selected policies from previous calls.
     *
     * Note: Criterias are all case-insensitive.
     * Note: Call `resetPolicyfilter()` to reset the selection filter and consider all
     * policies again.
     *
     * @param args A bag of options containing the selection criterias, or an array of cherry-picked policies.
     * @param enforcementLevel The desired policy enforcement Level. Valid values are `advisory`, `mandatory` and `disabled`.
     * @returns An array of ResourceValidationPolicy policies that matched with the selection criterias.
     */
    selectPolicies(args: FilterPolicyArgs | policy.ResourceValidationPolicy[], enforcementLevel?: string): policy.ResourceValidationPolicy[];
    /**
     * Register a new policy into the pool of policies. The policy name must be
     * unique to the pool of policies already registered or an exception is thrown.
     *
     * This function is used if you are authoring your own Compliance Policies.
     *
     * @param args An object containing the policy to register as well as its additional attributes.
     * @returns a `ResourceValidationPolicy` object.
     */
    registerPolicy(args: RegisterPolicyArgs): policy.ResourceValidationPolicy;
    /**
     * This function is used by policy module to register information about themselves.
     * This can be later used to display statistics about included packages as part of
     * a policy-pack.
     *
     * This function is to be used if you are authoring your own Compliance Policies.
     *
     * @param name Name of the policy module as stored in `package.json`
     * @param version The module version as stored in `package.json`
     * @returns returns the package version as a string
     */
    registerPolicyModule(name: string, version: string): string;
}
/**
 * An instance of the `PolicyManager` class.
 *
 * Use this instance to manipulate (register, select...) policies.
 */
export declare const policyManager: PolicyManager;
/**
 * The function `valToBoolean()` is a helper because some boolean properties
 * require a string type instead of a boolean type.
 * The idea for this function is to allow compatibility across multiple versions
 * of the same provider in case a property type changes from string to boolean.
 *
 * @link https://github.com/pulumi/pulumi-aws/issues/2257
 * @param val A value to convert into a boolean.
 * @returns The boolean value, or `undefined` is the conversion isn't possible.
 */
export declare function valToBoolean(val: boolean | string | undefined): boolean | undefined;