@cloud-copilot/iam-lens/dist/esm/whoCan/principalArnFilter.d.ts

Visibility in IAM in and across AWS accounts

/**
 * An action-scoped set of principal ARN patterns extracted from a Deny statement.
 * The patterns only apply when the action being simulated matches one of the
 * entry's action patterns.
 */
export interface DenyFilterEntry {
    /** Action patterns from the deny statement (e.g., 'secretsmanager:GetSecretValue', 's3:*'). */
    actionPatterns: string[];
    /** Principal ARN patterns extracted from the condition. */
    principalPatterns: RegExp[];
}
/**
 * A pre-simulation filter that uses aws:PrincipalArn condition patterns
 * from a resource policy to skip principals that cannot possibly be allowed.
 */
export interface PrincipalArnFilter {
    /**
     * Allow patterns extracted from resource policy Allow statements.
     * If non-empty, a principal must match at least one pattern to be
     * worth simulating.
     */
    allowPatterns: RegExp[];
    /**
     * From Deny statements with negative operators (StringNotLike, etc.).
     * For each entry, if the simulation action matches one of the entry's
     * action patterns, the principal must match at least one of the entry's
     * principal patterns to be worth simulating.
     */
    denyDerivedAllowEntries: DenyFilterEntry[];
    /**
     * From Deny statements with positive operators (StringLike, etc.).
     * For each entry, if the simulation action matches one of the entry's
     * action patterns AND the principal matches one of the entry's principal
     * patterns, the simulation can be skipped (the principal is explicitly denied).
     */
    denyEntries: DenyFilterEntry[];
    /**
     * Account IDs that are explicitly named as account principals in the
     * resource policy's Allow statements. Principals in these accounts
     * must bypass the filter because the account-level principal grant
     * is independent of any PrincipalArn conditions on wildcard statements.
     */
    exemptAccounts: Set<string>;
}
/**
 * Converts an IAM wildcard pattern to a case-sensitive anchored RegExp.
 * Handles `*` (any characters) and `?` (single character) wildcards.
 * Does not handle replacement variables — callers must ensure patterns
 * with variables are excluded before calling this.
 *
 * @param pattern the IAM pattern string (e.g. `arn:aws:iam::*:role/ec2/*`)
 * @returns an anchored case-sensitive RegExp
 */
export declare function iamPatternToRegex(pattern: string): RegExp;
/**
 * Builds a PrincipalArnFilter from a resource policy by extracting
 * aws:PrincipalArn patterns from Allow statements with wildcard principals.
 *
 * The filter is only constructed if **every** wildcard-Allow statement has
 * a usable aws:PrincipalArn condition. If any wildcard-Allow statement lacks
 * one, the filter cannot safely exclude principals and undefined is returned.
 *
 * @param resourcePolicy the raw resource policy document, or undefined/null if none
 * @returns a PrincipalArnFilter if filtering is possible, undefined otherwise
 */
export declare function buildPrincipalArnFilter(resourcePolicy: any): PrincipalArnFilter | undefined;
/**
 * Tests whether a principal ARN passes the PrincipalArnFilter for a given action.
 *
 * Principals in the resource account or an exempt account bypass the positive
 * allow-side filtering (allow patterns and deny-derived allow entries) because
 * they may be granted access through account-level principal grants independent
 * of any PrincipalArn conditions. However, they are still subject to deny-side
 * filtering (deny entries) because an explicit deny in a resource policy applies
 * regardless of the principal's account.
 *
 * @param principal the principal ARN to test
 * @param action the action being simulated
 * @param resourceAccount the account that owns the resource being checked
 * @param filter the filter to apply
 * @returns true if the principal should be simulated, false if it can be skipped
 */
export declare function principalMatchesFilter(principal: string, action: string, resourceAccount: string, filter: PrincipalArnFilter): boolean;
//# sourceMappingURL=principalArnFilter.d.ts.map