@infrascan/shared-types 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @infrascan/shared-types
 
+## 0.6.0
+
+### Minor Changes
+
+- [#89](https://github.com/infrascan/infrascan/pull/89) [`913867b73a72791c79a69ebfec8bf94331654c1d`](https://github.com/infrascan/infrascan/commit/913867b73a72791c79a69ebfec8bf94331654c1d) Thanks [@lfarrel6](https://github.com/lfarrel6)! - Migrate graph output to a standard schema for easier search/filter
+
+## 0.5.1
+
+### Patch Changes
+
+- [#84](https://github.com/infrascan/infrascan/pull/84) [`437026c`](https://github.com/infrascan/infrascan/commit/437026cc278ec4b380bcaf3a7a675f3762ce3bea) Thanks [@lfarrel6](https://github.com/lfarrel6)! - Bump aws client sdk versions to remove vulnerable dependency
+
 ## 0.5.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infrascan/shared-types",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared types for multiple infrascan packages",
   "main": "src/index.ts",
   "scripts": {
@@ -12,7 +12,7 @@
   "author": "Liam Farrelly <liam@l3f7.dev> (https://whoisli.am/)",
   "license": "MPL-2.0",
   "devDependencies": {
-    "@aws-sdk/types": "3.428.0",
+    "@aws-sdk/types": "3.609.0",
     "eslint-config-custom": "*",
     "tsconfig": "*",
     "typescript": "^5.1.6"

package/src/api.ts

@@ -1,7 +1,12 @@
-import type { AwsCredentialIdentityProvider, RetryStrategy, RetryStrategyV2 } from "@aws-sdk/types";
+import type {
+  AwsCredentialIdentityProvider,
+  RetryStrategy,
+  RetryStrategyV2,
+} from "@aws-sdk/types";
 
 import type { SelectedEdge, SelectedNode } from "./graph";
 import type { BaseEdgeResolver } from "./config";
+import type { TranslatedEntity, BaseState } from "./scan";
 
 /**
  * Callback to store state from a specific function call
@@ -73,7 +78,7 @@ export interface Connector {
 type ClientBuilder<T, P extends Provider> = (
   credentials: AwsCredentialIdentityProvider,
   context: ProviderContextMap[P],
-  retryStrategy?: RetryStrategy | RetryStrategyV2
+  retryStrategy?: RetryStrategy | RetryStrategyV2,
 ) => T;
 
 type GetterFn<T, P extends Provider> = (
@@ -112,7 +117,15 @@ export type EntityRoleData = {
 };
 type GetIamRoleFn = (stateConnector: Connector) => Promise<EntityRoleData[]>;
 
-export interface ServiceModule<T, P extends Provider> {
+export interface ServiceModule<
+  T,
+  P extends Provider,
+  E extends TranslatedEntity<BaseState, any, any> = TranslatedEntity<
+    BaseState,
+    any,
+    any
+  >,
+> {
   provider: P;
   service: string;
   arnLabel?: string;
@@ -120,9 +133,9 @@ export interface ServiceModule<T, P extends Provider> {
   getClient: ClientBuilder<T, P>;
   callPerRegion: boolean;
   getters: GetterFn<T, P>[];
-  nodes?: string[];
   getNodes?: GetNodeFn<P>;
   edges?: BaseEdgeResolver[];
   getEdges?: GetEdgeFn;
   getIamRoles?: GetIamRoleFn;
+  entities?: E[];
 }

package/src/config.ts

@@ -38,8 +38,6 @@ export type BaseScannerDefinition = {
   callPerRegion: boolean;
   // Scanner functions for pulling state from a service
   getters: BaseGetter[];
-  // Scrapers for pulling Nodes from service state
-  nodes?: GenericNodeSelector[];
   // Scrapers for pulling Edges from service state
   edges?: BaseEdgeResolver[];
   // Scrapers for pulling IAM Roles from service state, used to generate permission based edges
@@ -126,7 +124,6 @@ export type ScannerDefinition<
   skipClientBuilder?: boolean;
   callPerRegion: boolean;
   getters: ServiceGetter<ServiceName, Serv, Funcs>[];
-  nodes?: StateSelector<ServiceName, Serv, Funcs>[];
   edges?: EdgeSelector<ServiceName, Serv, Funcs>[];
   iamRoles?: StateSelector<ServiceName, Serv, Funcs>[];
 };

package/src/graph.ts

@@ -1,3 +1,5 @@
+import { BaseState } from "./scan";
+
 /**
  * A node returned from a state selector before its been formatted for a graphing library
  */
@@ -6,6 +8,7 @@ export interface SelectedNode {
   name?: string;
   parent?: string;
   type?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   rawState?: any;
 }
 
@@ -26,16 +29,19 @@ export type ElementType<ReadType, WriteType> = {
   readonly _write: WriteType;
 };
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ElementRecord<K extends keyof any, R, W> = ElementType<
   Record<K, Readable<R>>,
   Record<K, Writable<W>>
 >;
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ReadType<T> = T extends ElementType<infer R, any> ? Readable<R> : T;
 export type Readable<T> = {
   [K in keyof T]: ReadType<T[K]>;
 };
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type WriteType<T> = T extends ElementType<any, infer W>
   ? Writable<W>
   : T;
@@ -43,7 +49,14 @@ export type Writable<T> = {
   [K in keyof T]: WriteType<T[K]>;
 };
 
-export interface Node {
+export interface Node extends BaseState<unknown> {
+  parent?: ElementType<Node, string>;
+  children?: ElementRecord<string, Node, string>;
+  incomingEdges: ElementRecord<string, Edge, string>;
+  outgoingEdges: ElementRecord<string, Edge, string>;
+}
+
+export interface NodeOld {
   id: string;
   name: string;
   metadata: Record<string, unknown>;
@@ -66,12 +79,7 @@ export interface Edge {
 export interface Graph {
   nodes: Readable<Node>[];
   edges: Readable<Edge>[];
-  addNode: (
-    node: Pick<
-      Writable<Node>,
-      "id" | "name" | "metadata" | "parent" | "service" | "type"
-    >,
-  ) => void;
+  addNode: (node: BaseState<unknown>) => void;
   addEdge: (
     edge: Pick<Writable<Edge>, "name" | "source" | "target" | "metadata">,
   ) => void;

package/src/index.ts

@@ -1,5 +1,5 @@
 export * from "./api";
 export * from "./config";
 export * from "./graph";
-export * from "./scan";
-export * from "./plugins";
+export * from "./plugins";
+export * from "./scan";

package/src/plugins.ts

@@ -2,25 +2,39 @@ import { Graph } from "./graph";
 import { AwsContext } from "./api";
 
 // All supported events to trigger a plugin
-export type GraphPluginEvents = "onServiceComplete" | "onRegionComplete" | "onAccountComplete" | "onGraphComplete";
+export type GraphPluginEvents =
+  | "onServiceComplete"
+  | "onRegionComplete"
+  | "onAccountComplete"
+  | "onGraphComplete";
 
 /**
  * A plugin which is called everytime a service's nodes have been added to the graph.
  * Receives the current graph state, the service ID, and the current AWS Context.
  */
-export type OnServiceCompletePlugin = (graph: Graph, service: string, context: AwsContext) => void | Promise<void>;
+export type OnServiceCompletePlugin = (
+  graph: Graph,
+  service: string,
+  context: AwsContext,
+) => void | Promise<void>;
 
 /**
  * A plugin which is called everytime a region's nodes have been added to the graph.
  * Receives the current graph state, and the current AWS Context.
  */
-export type OnRegionCompletePlugin = (graph: Graph, context: AwsContext) => void | Promise<void>;
+export type OnRegionCompletePlugin = (
+  graph: Graph,
+  context: AwsContext,
+) => void | Promise<void>;
 
 /**
  * A plugin which is called everytime an account's nodes have been added to the graph.
  * Receives the current graph state, and the current AWS Context.
  */
-export type OnAccountCompletePlugin = (graph: Graph, context: AwsContext) => void | Promise<void>;
+export type OnAccountCompletePlugin = (
+  graph: Graph,
+  context: AwsContext,
+) => void | Promise<void>;
 
 /**
  * A plugin which is called when the entire graph has been generated.
@@ -29,14 +43,14 @@ export type OnAccountCompletePlugin = (graph: Graph, context: AwsContext) => voi
 export type OnGraphCompletePlugin = (graph: Graph) => void | Promise<void>;
 
 export type PluginEventHandlerTypes = {
-    "onServiceComplete": OnServiceCompletePlugin,
-    "onRegionComplete": OnRegionCompletePlugin,
-    "onAccountComplete": OnAccountCompletePlugin,
-    "onGraphComplete": OnGraphCompletePlugin,
+  onServiceComplete: OnServiceCompletePlugin;
+  onRegionComplete: OnRegionCompletePlugin;
+  onAccountComplete: OnAccountCompletePlugin;
+  onGraphComplete: OnGraphCompletePlugin;
 };
 
 export interface GraphPlugin<E extends GraphPluginEvents> {
-    id: string,
-    event: E,
-    handler: PluginEventHandlerTypes[E]
-}
+  id: string;
+  event: E;
+  handler: PluginEventHandlerTypes[E];
+}

package/src/scan.ts

@@ -1,12 +1,347 @@
-export type State<T> = {
-  _metadata: {
-    account: string;
-    region: string;
-  };
-  _result: T;
-  /* eslint-disable @typescript-eslint/no-explicit-any */
-  _parameters?: any;
+import { AwsContext, Connector } from "./api";
+
+export interface CommandCallMetadata {
+  account: string;
+  region: string;
+  partition?: string;
+  timestamp: number;
+}
+
+export interface State<O, I = unknown> {
+  _metadata: CommandCallMetadata;
+  _result: O;
+  _parameters?: I;
+}
+
+export type GenericState = State<unknown>;
+
+/**
+ * Metadata for any piece of state generated — when it was scanned, and what version of the state schema it uses
+ */
+export interface StateMetadata {
+  version: string;
+  /**
+   * Epoch value (in ms)
+   */
+  timestamp: number;
+}
+
+/**
+ * Coordinates of a node in the graph including an optional position on the Z axis
+ */
+export interface Coordinates {
+  x: number;
+  y: number;
+  z?: number;
+}
+
+/**
+ * Details about the nodes position in the graph and how it relates to other components
+ */
+export interface GraphInfo {
+  /**
+   * The unique ID of the node in the graph
+   */
+  id: string;
+  /**
+   * The human readable name of the node in the graph
+   */
+  label: string;
+  /**
+   * The type of the node, used for assigning an icon in the graph
+   */
+  nodeType: string;
+  /**
+   * The ID of the parent node, optional.
+   */
+  parent?: string;
+  /**
+   * The coordinates of the node in the graph, optional.
+   */
+  coords?: Coordinates;
+}
+
+/**
+ * The tenant that the resource has been created in, typically an account or org. Should be defined for every resource.
+ */
+export interface Tenant {
+  /**
+   * CSP that the state refers to (aws, gcp, azure)
+   */
+  provider: string;
+  /**
+   * The partition of this state e.g. govcloud, cn partitions
+   */
+  partition?: string;
+  /**
+   * The unique ID for the tenant (e.g. account id)
+   */
+  tenantId: string;
+}
+
+/**
+ * The geo data for a resource tracking where it is deployed to and, if known, which specific zones (i.e. datacenters) its in.
+ */
+export interface Location {
+  /**
+   * The standard reference name for the region e.g. us-east-1
+   */
+  code: string;
+  /**
+   * The availability zone/datacenter that the resource is in e.g. us-east-1a
+   */
+  zone?: string[];
+}
+
+/**
+ * Details which identify a resource within the state
+ */
+export interface Resource {
+  /**
+   * Category tracks whether this resource is a higher level concept like an account, or a service of a resource
+   */
+  category: string;
+  /**
+   * Subcategory tracks the resource's more specific resource type e.g. sub-service entity type. Not set for higher level concepts
+   */
+  subcategory?: string;
+  /**
+   * The unique ID of the resource — either an account number or a resource ID
+   */
+  id: string;
+  /**
+   * The human-readable name of the resource
+   */
+  name: string;
+  /**
+   * The recorded description for the resource
+   */
+  description?: string;
+  /**
+   * The resource level policy which dictates access
+   */
+  policy?: string;
+}
+
+export interface Role {
+  arn: string;
+  label: string;
+}
+
+/**
+ * The IAM roles associated with a resource. Supports resources with many roles assigned to varying lifecycles
+ */
+export interface IAM {
+  roles: Role[];
+}
+
+/**
+ * The audit details of any existing resource where available - tracks who created the resource and when.
+ */
+export interface Audit {
+  createdAt?: string | Date;
+  createdBy?: string;
+}
+
+/**
+ * The domain names that a resource can be accessed at
+ */
+export interface DNS {
+  /**
+   * List of domain names at which a resource is accessible
+   */
+  domains: string[];
+}
+
+export type PublicIpStatus = "enabled" | "disabled";
+
+/**
+ * The network information for a scanned resource which aims to cover both resources being assigned an address
+ * and the networking resource itself (VPC, subnet)
+ */
+export interface Network {
+  /**
+   * Information about the public IP of the resource
+   */
+  publicIp?: {
+    status?: PublicIpStatus;
+    address?: string;
+  };
+  /**
+   * List of security group IDs that are associated with the resource
+   */
+  securityGroups?: string[];
+  /**
+   * The subnets that the resource is deployed into
+   */
+  targetSubnets?: string[];
+  /**
+   * The IPs that have been assigned to the resource within the private network.
+   */
+  assignedAddresses?: {
+    ipv4?: string;
+    ipv6?: string;
+  };
+  /**
+   * The IP ranges reserved for a networking resource (VPC, subnet)
+   */
+  reservedAddresses?: [
+    {
+      family: "ipv4" | "ipv6";
+      cidrBlock: string;
+      cidrBlockAssociationSets?: [
+        {
+          associationId: string;
+          cidrBlock: string;
+          state: string;
+          stateMessage: string;
+        },
+      ];
+      firstAddress: string;
+      lastAddress: string;
+    },
+  ];
+  /**
+   * The information relating to a specific subnet
+   */
+  subnet?: {
+    ipv6Only?: boolean;
+    availableAddressCount?: number;
+  };
+  /**
+   * The information relating to a specific VPC.
+   */
+  vpc?: {
+    id?: string;
+    dhcpOptionsId?: string;
+    state?: string;
+    instanceTenancy?: string;
+    default?: boolean;
+  };
+}
+
+/**
+ * Generic structure for tracking key value datatypes
+ */
+export interface KVPair {
+  key?: string;
+  value?: string;
+}
+
+/**
+ * Structure for tracking the source of state that was scanned
+ */
+export interface Source<T> {
+  command: string;
+  parameters?: T;
+}
+
+/**
+ * Structure for representing the relationship between resources and the load balancers that route to them
+ */
+export interface LoadBalancer {
+  name?: string;
+  port?: number;
+  targetGroupArn?: string;
+}
+
+export type SizeUnit = "B" | "MB" | "MiB" | "GB" | "GiB";
+
+export type TimeUnit = "s" | "ms" | "m" | "h" | "d";
+
+export interface QualifiedMeasure<T> {
+  unit: T;
+  value: number;
+}
+
+export interface HealthcheckConfig {
+  status?: string;
+  gracePeriod?: QualifiedMeasure<TimeUnit>;
+}
+
+/**
+ * Structure for tracking resources which have an associated encryption key
+ */
+export interface EncryptionConfig {
+  keyId?: string;
+}
+
+export interface DeadLetterConfig {
+  targetId?: string;
+}
+
+/**
+ * Base state type to be extended on a per-service basis with the service specific context to use for linking.
+ * Attribute specific information can be found on each type.
+ */
+export interface BaseState<T = unknown> {
+  $metadata: StateMetadata;
+  $graph: GraphInfo;
+  $source?: Source<T>;
+  deadLetter?: DeadLetterConfig;
+  tenant: Tenant;
+  location?: Location;
+  loadBalancers?: LoadBalancer[];
+  resource: Resource;
+  dns?: DNS;
+  iam?: IAM;
+  healthcheck?: HealthcheckConfig;
+  network?: Network;
+  audit?: Audit;
+  tags?: KVPair[];
+  encryption?: EncryptionConfig;
+}
+
+/**
+ * Generic type signature for any ode responsible for translating between data types
+ */
+type Translate<A, B> = (val: A) => B;
+
+/**
+ * Definition of a an entity's translators to convert the raw input state into the common schema
+ */
+export type ComponentFactory<Input, Schema = BaseState<unknown>> = {
+  [ComponentName in keyof Schema]: Translate<Input, Schema[ComponentName]>;
 };
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
-export type GenericState = State<any>;
+export interface CommonEntity<Schema, RawState, TranslatedState = RawState> {
+  version: string;
+  selector: string;
+  debugLabel: string;
+  provider: string;
+  command: string;
+  category: string;
+  subcategory: string;
+  nodeType: string;
+
+  getState: (state: Connector, context: AwsContext) => Promise<RawState[]>;
+  components: ComponentFactory<TranslatedState, Schema>;
+}
+
+/**
+ * Entity which can act directly on its raw state, and does not require any pre-processing before
+ */
+export interface SimpleEntity<Schema, RawState>
+  extends CommonEntity<Schema, RawState> {
+  translate?: never;
+}
+
+/**
+ * Entity which needs to translate its stored raw state before it can produce the standard schema
+ */
+export interface TranslatedEntity<Schema, RawState, TranslatedState>
+  extends CommonEntity<Schema, RawState, TranslatedState> {
+  translate: Translate<RawState, TranslatedState[]>;
+}
+
+/**
+ * Discriminated union type for both simple and translated entities
+ */
+export type EntityETL<Schema, RawState, TranslatedState = RawState> =
+  | SimpleEntity<Schema, RawState>
+  | TranslatedEntity<Schema, RawState, TranslatedState>;
+
+export type WithCallContext<T, Input> = T & {
+  $metadata: CommandCallMetadata;
+  $parameters?: Input;
+};