@etcsec-com/etc-collector 1.4.0

package/src/types/finding.types.ts

@@ -0,0 +1,284 @@
+/**
+ * Vulnerability Finding Types
+ *
+ * Type definitions for security vulnerability findings.
+ * Story 1.7: AD Vulnerability Detection Engine
+ */
+
+/**
+ * Enriched user entity for affectedEntities
+ * Contains AD attributes for detailed reporting
+ */
+export interface AffectedUserEntity {
+  // Type discriminator
+  type: 'user';
+
+  // Identity (5)
+  dn: string;
+  sAMAccountName: string;
+  userPrincipalName: string | null;
+  displayName: string | null;
+  mail: string | null;
+
+  // Organization (8)
+  title: string | null;
+  department: string | null;
+  company: string | null;
+  manager: string | null;
+  physicalDeliveryOfficeName: string | null;
+  description: string | null;
+  employeeID: string | null;
+  telephoneNumber: string | null;
+
+  // Dates (5)
+  whenCreated: string | null;
+  whenChanged: string | null;
+  lastLogon: string | null;
+  pwdLastSet: string | null;
+  accountExpires: string | null;
+
+  // Security (4)
+  badPwdCount: number;
+  lockoutTime: string | null;
+  adminCount: number;
+  memberOf: string[];
+  enabled: boolean;
+}
+
+/**
+ * Enriched Azure user entity for affectedEntities
+ * Contains Azure AD/Entra ID attributes for detailed reporting
+ */
+export interface AffectedAzureUserEntity {
+  // Type discriminator
+  type: 'azureUser';
+
+  // Identity (5)
+  id: string;
+  userPrincipalName: string;
+  displayName: string | null;
+  mail: string | null;
+  givenName: string | null;
+  surname: string | null;
+
+  // Organization (6)
+  jobTitle: string | null;
+  department: string | null;
+  companyName: string | null;
+  manager: string | null;
+  officeLocation: string | null;
+  employeeId: string | null;
+
+  // Dates (3)
+  createdDateTime: string | null;
+  lastSignInDateTime: string | null;
+  lastPasswordChangeDateTime: string | null;
+
+  // Security (7)
+  accountEnabled: boolean;
+  userType: string | null; // "Member" | "Guest"
+  riskLevel: string | null; // "none" | "low" | "medium" | "high" | "hidden"
+  riskState: string | null; // "none" | "confirmedSafe" | "remediated" | "dismissed" | "atRisk" | "confirmedCompromised"
+  isMfaRegistered: boolean;
+  assignedLicenses: string[];
+  memberOf: string[]; // Group/role IDs or names
+}
+
+/**
+ * Enriched application entity for affectedEntities
+ * Used for Azure AD applications and service principals
+ */
+export interface AffectedAppEntity {
+  id: string; // appId or objectId
+  displayName: string;
+  type: 'application' | 'servicePrincipal';
+
+  // App details
+  appId: string | null;
+  signInAudience: string | null; // "AzureADMyOrg" | "AzureADMultipleOrgs" | etc.
+  createdDateTime: string | null;
+
+  // Security
+  publisherDomain: string | null;
+  verifiedPublisher: boolean;
+  credentialCount: number;
+  oldestCredentialExpiry: string | null;
+}
+
+/**
+ * Enriched group entity for affectedEntities
+ * Used for both AD and Azure groups
+ */
+export interface AffectedGroupEntity {
+  id: string; // DN for AD, objectId for Azure
+  displayName: string;
+  type: 'group';
+
+  // AD-specific
+  sAMAccountName: string | null;
+  groupType: string | null; // "Security" | "Distribution"
+  groupScope: string | null; // "DomainLocal" | "Global" | "Universal"
+
+  // Azure-specific
+  securityEnabled: boolean | null;
+  mailEnabled: boolean | null;
+  groupTypes: string[]; // ["Unified", "DynamicMembership"]
+
+  // Common
+  memberCount: number | null;
+  description: string | null;
+}
+
+/**
+ * Enriched computer entity for affectedEntities
+ * Used for AD computer objects
+ */
+export interface AffectedComputerEntity {
+  id: string; // DN
+  displayName: string;
+  type: 'computer';
+
+  // Identity
+  sAMAccountName: string;
+  dNSHostName: string | null;
+
+  // OS Info
+  operatingSystem: string | null;
+  operatingSystemVersion: string | null;
+
+  // Dates
+  whenCreated: string | null;
+  whenChanged: string | null;
+  lastLogon: string | null;
+  pwdLastSet: string | null;
+
+  // Security
+  enabled: boolean;
+  userAccountControl: number;
+}
+
+/**
+ * Vulnerability severity levels
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low';
+
+/**
+ * Vulnerability category
+ */
+export type Category =
+  | 'passwords'
+  | 'kerberos'
+  | 'accounts'
+  | 'groups'
+  | 'computers'
+  | 'advanced'
+  | 'permissions'
+  | 'config'
+  | 'adcs' // AD Certificate Services (ESC1-ESC11)
+  | 'gpo' // Group Policy security
+  | 'trusts' // Domain trust relationships
+  | 'attack-paths' // Privilege escalation paths (Phase 2)
+  | 'monitoring' // Security monitoring gaps (Phase 2)
+  | 'compliance' // Security framework compliance (Phase 3)
+  | 'network' // Network infrastructure security (Phase 3)
+  | 'identity' // Azure AD identity vulnerabilities
+  | 'applications' // Azure AD applications
+  | 'conditionalAccess' // Azure Conditional Access
+  | 'privilegedAccess'; // Azure privileged access
+
+/**
+ * Single vulnerability finding
+ */
+export interface Finding {
+  /**
+   * Vulnerability type identifier (e.g., "PASSWORD_NOT_REQUIRED")
+   */
+  type: string;
+
+  /**
+   * Severity level
+   */
+  severity: Severity;
+
+  /**
+   * Category classification
+   */
+  category: Category;
+
+  /**
+   * Human-readable title
+   */
+  title: string;
+
+  /**
+   * Detailed description
+   */
+  description: string;
+
+  /**
+   * Number of affected entities (unique objects)
+   * Used for scoring and actionable remediation
+   */
+  count: number;
+
+  /**
+   * Total instances found (e.g., total ACE entries for permissions)
+   * Optional - only present when count differs from total instances
+   * Used for forensics and detailed audit trail
+   */
+  totalInstances?: number;
+
+  /**
+   * List of affected entities (optional, if includeDetails=true)
+   * Can be enriched entity objects with type discriminator for uniform aggregation
+   */
+  affectedEntities?: (
+    | string
+    | AffectedUserEntity
+    | AffectedAzureUserEntity
+    | AffectedAppEntity
+    | AffectedGroupEntity
+    | AffectedComputerEntity
+  )[];
+
+  /**
+   * Additional context-specific details
+   */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Finding counts by severity
+ */
+export interface FindingCounts {
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  total: number;
+}
+
+/**
+ * Finding counts by category
+ */
+export interface CategoryCounts {
+  passwords: number;
+  kerberos: number;
+  accounts: number;
+  groups: number;
+  computers: number;
+  advanced: number;
+  permissions: number;
+  config: number;
+  adcs: number;
+  gpo: number;
+  trusts: number;
+  'attack-paths': number;
+  monitoring: number;
+  compliance: number;
+  network: number;
+  identity: number;
+  applications: number;
+  conditionalAccess: number;
+  privilegedAccess: number;
+}

package/src/types/gpo.types.ts

@@ -0,0 +1,72 @@
+/**
+ * GPO (Group Policy Object) Types
+ *
+ * Types for GPO security analysis.
+ */
+
+/**
+ * Group Policy Object
+ */
+export interface ADGPO {
+  dn: string;
+  cn: string; // GUID
+  displayName?: string;
+  gPCFileSysPath?: string;
+
+  // Flags: 0=enabled, 1=user disabled, 2=computer disabled, 3=all disabled
+  flags?: number;
+
+  // Version info
+  versionNumber?: number;
+
+  // Security descriptor for ACL analysis
+  nTSecurityDescriptor?: Buffer;
+
+  // Machine/User extension GUIDs (for detecting LAPS, etc.)
+  gPCMachineExtensionNames?: string;
+  gPCUserExtensionNames?: string;
+
+}
+
+/**
+ * GPO Link information
+ */
+export interface GPOLink {
+  gpoGuid: string;
+  gpoDn?: string;
+  linkedTo: string; // OU/Domain DN
+  linkOrder?: number;
+  enforced: boolean;
+  disabled: boolean;
+}
+
+/**
+ * GPO ACL Entry for permission analysis
+ */
+export interface GPOAclEntry {
+  gpoDn: string;
+  gpoName: string;
+  trustee: string;
+  trusteeSid: string;
+  accessMask: number;
+  aceType: number;
+}
+
+// GPO Flags
+export const GPO_FLAG_USER_DISABLED = 0x00000001;
+export const GPO_FLAG_COMPUTER_DISABLED = 0x00000002;
+export const GPO_FLAG_ALL_DISABLED = 0x00000003;
+
+// GPO Link Flags (from gPOptions)
+export const GPO_LINK_DISABLED = 0x00000001;
+export const GPO_LINK_ENFORCED = 0x00000002;
+
+// LAPS Client-Side Extension GUID
+export const LAPS_CSE_GUID = '{D76B9641-3288-4f75-942D-087DE603E3EA}';
+export const LAPS_LEGACY_CSE_GUID = '{169EBF44-942F-4C43-87CE-13C93996EBBE}';
+
+// Common GPO rights
+export const GPO_RIGHT_WRITE = 0x00000002;
+export const GPO_RIGHT_WRITE_DAC = 0x00040000;
+export const GPO_RIGHT_WRITE_OWNER = 0x00080000;
+export const GPO_RIGHT_GENERIC_WRITE = 0x40000000;

package/src/types/smb2.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Type declarations for @marsaud/smb2
+ */
+
+declare module '@marsaud/smb2' {
+  interface SMB2Options {
+    share: string;
+    domain: string;
+    username: string;
+    password: string;
+    autoCloseTimeout?: number;
+  }
+
+  interface ReadFileOptions {
+    encoding?: BufferEncoding;
+  }
+
+  class SMB2 {
+    constructor(options: SMB2Options);
+
+    readFile(
+      path: string,
+      options: ReadFileOptions,
+      callback: (err: Error | null, data: string | Buffer) => void
+    ): void;
+
+    readFile(
+      path: string,
+      callback: (err: Error | null, data: Buffer) => void
+    ): void;
+
+    writeFile(
+      path: string,
+      data: string | Buffer,
+      callback: (err: Error | null) => void
+    ): void;
+
+    readdir(
+      path: string,
+      callback: (err: Error | null, files: string[]) => void
+    ): void;
+
+    exists(
+      path: string,
+      callback: (err: Error | null, exists: boolean) => void
+    ): void;
+
+    unlink(
+      path: string,
+      callback: (err: Error | null) => void
+    ): void;
+
+    rename(
+      oldPath: string,
+      newPath: string,
+      callback: (err: Error | null) => void
+    ): void;
+
+    mkdir(
+      path: string,
+      callback: (err: Error | null) => void
+    ): void;
+
+    rmdir(
+      path: string,
+      callback: (err: Error | null) => void
+    ): void;
+
+    close(callback?: (err: Error | null) => void): void;
+  }
+
+  export = SMB2;
+}

package/src/types/token.types.ts

@@ -0,0 +1,32 @@
+/**
+ * Token Types
+ */
+
+export type TokenStatus = 'valid' | 'expired' | 'revoked' | 'max_uses_exceeded';
+
+export interface TokenPayload {
+  jti: string; // JWT ID
+  iat: number; // Issued at (Unix timestamp)
+  exp: number; // Expires at (Unix timestamp)
+  maxUses: number;
+  metadata?: Record<string, string>;
+}
+
+export interface TokenInfo {
+  jti: string;
+  createdAt: string;
+  expiresAt: string;
+  maxUses: number;
+  usedCount: number;
+  status: TokenStatus;
+  revoked: boolean;
+  revokedAt?: string;
+  revokedReason?: string;
+}
+
+export interface TokenUsage {
+  jti: string;
+  usedAt: string;
+  usedCount: number;
+  remainingUses: number;
+}

package/src/types/trust.types.ts

@@ -0,0 +1,140 @@
+/**
+ * Domain Trust Types
+ *
+ * Enhanced types for trust relationship security analysis.
+ */
+
+/**
+ * Extended Trust Relationship with security analysis fields
+ */
+export interface ADTrustExtended {
+  name: string;
+  dn: string;
+
+  // Direction
+  trustDirection: number; // 1=inbound, 2=outbound, 3=bidirectional
+  direction: 'inbound' | 'outbound' | 'bidirectional';
+
+  // Type
+  trustType: number;
+  type: 'forest' | 'external' | 'realm' | 'shortcut' | 'parent-child';
+
+  // Attributes for security analysis
+  trustAttributes: number;
+
+  // Computed security flags
+  sidFilteringEnabled: boolean;
+  selectiveAuthEnabled: boolean;
+  isTransitive: boolean;
+
+  // Partner domain info
+  flatName?: string;
+  trustPartner?: string;
+
+  // Encryption types (msDS-SupportedEncryptionTypes)
+  // Bit flags: 0x1=DES-CBC-CRC, 0x2=DES-CBC-MD5, 0x4=RC4-HMAC, 0x8=AES128, 0x10=AES256
+  supportedEncryptionTypes?: number;
+
+  // Dates for activity detection
+  whenCreated?: Date;
+  whenChanged?: Date;
+}
+
+// Trust Direction values
+export const TRUST_DIRECTION_INBOUND = 1;
+export const TRUST_DIRECTION_OUTBOUND = 2;
+export const TRUST_DIRECTION_BIDIRECTIONAL = 3;
+
+// Trust Type values
+export const TRUST_TYPE_DOWNLEVEL = 1; // Windows NT domain
+export const TRUST_TYPE_UPLEVEL = 2; // Active Directory domain
+export const TRUST_TYPE_MIT = 3; // Kerberos realm (non-Windows)
+export const TRUST_TYPE_DCE = 4; // DCE realm
+
+// Trust Attribute bit flags
+export const TRUST_ATTRIBUTE_NON_TRANSITIVE = 0x00000001;
+export const TRUST_ATTRIBUTE_UPLEVEL_ONLY = 0x00000002;
+export const TRUST_ATTRIBUTE_QUARANTINED_DOMAIN = 0x00000004; // SID filtering enabled
+export const TRUST_ATTRIBUTE_FOREST_TRANSITIVE = 0x00000008;
+export const TRUST_ATTRIBUTE_CROSS_ORGANIZATION = 0x00000010; // Selective authentication
+export const TRUST_ATTRIBUTE_WITHIN_FOREST = 0x00000020;
+export const TRUST_ATTRIBUTE_TREAT_AS_EXTERNAL = 0x00000040;
+export const TRUST_ATTRIBUTE_USES_RC4_ENCRYPTION = 0x00000080;
+export const TRUST_ATTRIBUTE_CROSS_ORGANIZATION_NO_TGT_DELEGATION = 0x00000200;
+export const TRUST_ATTRIBUTE_PIM_TRUST = 0x00000400;
+
+/**
+ * Helper function to parse trust direction
+ */
+export function parseTrustDirection(direction: number): 'inbound' | 'outbound' | 'bidirectional' {
+  switch (direction) {
+    case TRUST_DIRECTION_INBOUND:
+      return 'inbound';
+    case TRUST_DIRECTION_OUTBOUND:
+      return 'outbound';
+    case TRUST_DIRECTION_BIDIRECTIONAL:
+      return 'bidirectional';
+    default:
+      return 'inbound';
+  }
+}
+
+/**
+ * Helper function to parse trust type
+ */
+export function parseTrustType(type: number, attributes: number): 'forest' | 'external' | 'realm' | 'shortcut' | 'parent-child' {
+  // Check if it's a forest trust
+  if ((attributes & TRUST_ATTRIBUTE_FOREST_TRANSITIVE) !== 0) {
+    return 'forest';
+  }
+
+  // Check if within forest (parent-child)
+  if ((attributes & TRUST_ATTRIBUTE_WITHIN_FOREST) !== 0) {
+    return 'parent-child';
+  }
+
+  switch (type) {
+    case TRUST_TYPE_MIT:
+      return 'realm';
+    case TRUST_TYPE_UPLEVEL:
+    case TRUST_TYPE_DOWNLEVEL:
+    default:
+      return 'external';
+  }
+}
+
+/**
+ * Check if SID filtering is enabled
+ */
+export function isSidFilteringEnabled(attributes: number): boolean {
+  return (attributes & TRUST_ATTRIBUTE_QUARANTINED_DOMAIN) !== 0;
+}
+
+/**
+ * Check if selective authentication is enabled
+ */
+export function isSelectiveAuthEnabled(attributes: number): boolean {
+  return (attributes & TRUST_ATTRIBUTE_CROSS_ORGANIZATION) !== 0;
+}
+
+/**
+ * Check if trust is transitive
+ */
+export function isTrustTransitive(attributes: number): boolean {
+  return (attributes & TRUST_ATTRIBUTE_NON_TRANSITIVE) === 0;
+}
+
+/**
+ * Parse trust attributes to extract all security-relevant properties
+ */
+export function parseTrustAttributes(attributes: number): {
+  sidFilteringEnabled: boolean;
+  selectiveAuthEnabled: boolean;
+  isTransitive: boolean;
+} {
+  return {
+    sidFilteringEnabled: isSidFilteringEnabled(attributes),
+    selectiveAuthEnabled: isSelectiveAuthEnabled(attributes),
+    isTransitive: isTrustTransitive(attributes),
+  };
+}