@infrascan/shared-types 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infrascan/shared-types",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Shared types for multiple infrascan packages",
   "main": "src/index.ts",
   "scripts": {

package/src/api.ts

@@ -6,6 +6,7 @@ import type {
 
 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
@@ -116,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;
@@ -124,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
@@ -47,8 +45,10 @@ export type BaseScannerDefinition = {
 };
 
 type AsCommand<S extends string> = `${S}Command`;
-export type AvailableCommand<Serv extends object, Funcs extends string> =
-  AsCommand<Funcs> extends `${infer P}Command` & keyof Serv ? P : never;
+export type AvailableCommand<
+  Serv extends object,
+  Funcs extends string,
+> = AsCommand<Funcs> extends `${infer P}Command` & keyof Serv ? P : never;
 
 export type StateSelector<
   ServiceName extends string,
@@ -124,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/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;
+};