@infrascan/shared-types 0.2.0

package/.eslintrc.js

@@ -0,0 +1,9 @@
+module.exports = {
+  extends: ["custom"],
+  root: true,
+  parserOptions: {
+    project: "./tsconfig.json",
+    tsconfigRootDir: __dirname
+  },
+  ignorePatterns: [".eslintrc.js"]
+}

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @infrascan/shared-types
+
+## 0.2.0
+
+### Minor Changes
+
+- 7d71a0e: Restructure the project into per service scanner modules. Each module must be registered with the SDK for the service to be scanned and graphed.
+
+  The initial implementation for Infrascan used a single config file which defined the scanning approach for every service, and their graph structure. It very quickly became difficult to debug, and reason about. The core logic was also completely untestable in any sane way.
+
+  This release is a rewrite of the entire project. The SDK by default will do nothing. Each individual service's scanner has to be registered into an instance of the SDK for it to be scanned or graphed. This reduces the SDK complexity massively, as it only needs to step through the registered services and call into their APIs.

package/README.md

@@ -0,0 +1,3 @@
+# @infrascan/shared-types
+
+Infrascan shared-types defines the common type interfaces for the SDK, Config and CLI.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@infrascan/shared-types",
+  "version": "0.2.0",
+  "description": "Shared types for multiple infrascan packages",
+  "main": "src/index.ts",
+  "scripts": {
+    "lint": "tsc --noEmit ; eslint ."
+  },
+  "keywords": [],
+  "author": "Liam Farrelly <liam@l3f7.dev> (https://whoisli.am/)",
+  "license": "MPL-2.0",
+  "dependencies": {
+    "@aws-sdk/client-apigatewayv2": "3.428.0",
+    "@aws-sdk/client-auto-scaling": "3.428.0",
+    "@aws-sdk/client-cloudfront": "3.428.0",
+    "@aws-sdk/client-cloudwatch-logs": "3.428.0",
+    "@aws-sdk/client-dynamodb": "3.428.0",
+    "@aws-sdk/client-ec2": "3.428.0",
+    "@aws-sdk/client-ecs": "3.428.0",
+    "@aws-sdk/client-elastic-load-balancing-v2": "3.428.0",
+    "@aws-sdk/client-iam": "3.428.0",
+    "@aws-sdk/client-lambda": "3.428.0",
+    "@aws-sdk/client-rds": "3.428.0",
+    "@aws-sdk/client-route-53": "3.428.0",
+    "@aws-sdk/client-s3": "3.428.0",
+    "@aws-sdk/client-sns": "3.428.0",
+    "@aws-sdk/client-sqs": "3.428.0",
+    "@aws-sdk/client-sts": "3.428.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/types": "3.428.0",
+    "eslint-config-custom": "*",
+    "tsconfig": "*",
+    "typescript": "^5.1.6"
+  }
+}

package/src/api.ts

@@ -0,0 +1,138 @@
+import type { AwsCredentialIdentityProvider } from "@aws-sdk/types";
+
+import type { Service } from "./services";
+import type { BaseEdgeResolver } from "./config";
+import type { GraphEdge, GraphNode } from "./graph";
+
+
+/**
+ * Callback to store state from a specific function call
+ *
+ * This is callback is invoked after every full scan of a service endpoint.
+ */
+export type ServiceScanCompleteCallbackFn = (
+  /**
+   * The AWS account being scanned
+   */
+  account: string,
+  /**
+   * The region being scanned
+   */
+  region: string,
+  /**
+   * The service being scanned
+   */
+  service: Service | "IAM",
+  /**
+   * The specific function called during scanning
+   */
+  functionName: string,
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  /**
+   * The state retrieved from the function call
+   */
+  functionState: any,
+) => Promise<void>;
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Callback to load scan state from a specific service call.
+ *
+ * This is used by the scan function pull back parameters for future function calls
+ * A common pattern is to have resources listed, and then described.
+ */
+export type ResolveStateForServiceFunction = (
+  /**
+   * The AWS account that was scanned
+   */
+  account: string,
+  /**
+   * The scanned region
+   */
+  region: string,
+  /**
+   * The scanned service e.g. Lambda
+   */
+  service: Service,
+  /**
+   * The specific function called during the scan e.g. GetFunction
+   */
+  functionName: string,
+) => Promise<any>;
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type GetGlobalStateForServiceFunction = (
+  service: string,
+  functionName: string,
+) => Promise<any>;
+
+export interface Connector {
+  onServiceScanCompleteCallback: ServiceScanCompleteCallbackFn;
+  resolveStateForServiceFunction: ResolveStateForServiceFunction;
+  getGlobalStateForServiceFunction: GetGlobalStateForServiceFunction;
+};
+
+type ClientBuilder<T, P extends Provider> = (
+  credentials: AwsCredentialIdentityProvider,
+  context: ProviderContextMap[P],
+) => T;
+
+type GetterFn<T, P extends Provider> = (
+  client: T,
+  stateConnector: Connector,
+  context: ProviderContextMap[P]
+) => Promise<void>;
+
+type GetNodeFn<T extends Provider> = (
+  stateConnector: Connector,
+  context: ProviderContextMap[T]
+) => Promise<GraphNode[]>;
+
+type GetEdgeFn = (stateConnector: Connector) => Promise<GraphEdge[]>;
+
+
+export type Provider = "aws";
+
+export type AwsContext = {
+  account: string;
+  region: string;
+  partition?: string;
+};
+
+type ProviderContextMap = {
+  aws: AwsContext
+}
+
+export type ProviderContext<T extends Provider> = {
+  provider: T;
+  context: ProviderContextMap[T];
+};
+
+type FormatNodeFn<P extends Provider> = (node: GraphNode, context: ProviderContextMap[P]) => GraphNode;
+type FormatEdgeFn<P extends Provider> = (
+  node: GraphEdge,
+  context: ProviderContextMap[P]
+) => GraphEdge;
+
+export type EntityRoleData = {
+  roleArn: string;
+  executor: string;
+};
+type GetIamRoleFn = (stateConnector: Connector) => Promise<EntityRoleData[]>;
+
+export interface ServiceModule<T, P extends Provider> {
+  provider: P;
+  service: string;
+  arnLabel?: string;
+  key: string;
+  getClient: ClientBuilder<T, P>;
+  callPerRegion: boolean;
+  getters: GetterFn<T, P>[];
+  nodes?: string[];
+  getNodes?: GetNodeFn<P>;
+  formatNode?: FormatNodeFn<P>;
+  edges?: BaseEdgeResolver[];
+  getEdges?: GetEdgeFn;
+  formatEdge?: FormatEdgeFn<P>;
+  getIamRoles?: GetIamRoleFn;
+};

package/src/config.ts

@@ -0,0 +1,134 @@
+export type GenericEdgeSelector = `${string}|${string}`;
+
+export type BaseEdgeResolver = {
+  state: GenericEdgeSelector;
+  from: string;
+  to: string;
+};
+
+export type PaginationToken = {
+  request?: string;
+  response?: string;
+};
+
+export type BaseGetter = {
+  id?: string;
+  fn: string;
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  parameters?: (BaseParameterResolver & { Value?: any, Selector?: string })[];
+  formatter?: string;
+  paginationToken?: PaginationToken;
+  iamRoleSelectors?: string[];
+};
+
+export type GenericNodeSelector = `${string}|${string}|${string}`;
+
+export type BaseScannerDefinition = {
+  provider?: string;
+  // Name of the service to be scanned
+  service: string;
+  // Key of the client in imported SDK
+  clientKey: string;
+  // Label used to identify this service within AWS ARNs
+  arnLabel?: string;
+  // Default 'type' for the generated graph entities, useful for applying a default style to a service's nodes.
+  key: string;
+  // Should the codegen skip implementing the client builder. Defaults to false.
+  skipClientBuilder?: boolean;
+  // Should this scanner be called in every region, or is it considered global (e.g. S3, Cloudfront, Route53)
+  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
+  iamRoles?: GenericNodeSelector[];
+};
+
+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 StateSelector<
+  ServiceName extends string,
+  Serv extends object,
+  Funcs extends string,
+> = `${ServiceName}|${AvailableCommand<Serv, Funcs>}|${string}`;
+
+export type EdgeSelector<
+  ServiceName extends string,
+  Serv extends object,
+  Funcs extends string,
+> = {
+  state: StateSelector<ServiceName, Serv, Funcs>;
+  to: string;
+  from: string;
+};
+
+export type BaseParameterResolver = {
+  Key: string;
+};
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type ConstantParameterResolver = {
+  Value: any;
+} & BaseParameterResolver;
+
+export type StatefulParameterResolver<
+  ServiceName extends string,
+  Serv extends object,
+  Funcs extends string,
+> = {
+  Selector: StateSelector<ServiceName, Serv, Funcs>;
+} & BaseParameterResolver;
+
+export type GenericStatefulParameterResolver = {
+  Selector: string;
+} & BaseParameterResolver;
+
+export type ParameterResolver<
+  ServiceName extends string,
+  Serv extends object,
+  Funcs extends string,
+> =
+  | ConstantParameterResolver
+  | StatefulParameterResolver<ServiceName, Serv, Funcs>;
+
+export type GenericParameterResolver = BaseParameterResolver & {
+  Selector?: string;
+  Value?: any;
+};
+
+export type ServiceGetter<
+  ServiceName extends string,
+  Serv extends object,
+  Funcs extends string,
+> = {
+  id?: string;
+  fn: AvailableCommand<Serv, Funcs>;
+  paginationToken?: PaginationToken;
+  parameters?: ParameterResolver<ServiceName, Serv, Funcs>[];
+  iamRoleSelectors?: string[];
+};
+
+export type ScannerDefinition<
+  ServiceName extends string,
+  Serv extends object,
+  Funcs extends string,
+> = {
+  provider: string;
+  service: string;
+  clientKey: ServiceName;
+  arnLabel?: string;
+  key: string;
+  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

@@ -0,0 +1,70 @@
+/**
+ * A node returned from a state selector before its been formatted for a graphing library
+ */
+export type SelectedNode = {
+  id: string;
+  name?: string;
+  parent?: string;
+  type?: string;
+  rawState?: any;
+};
+
+/**
+ * A node on the graph
+ */
+export type GraphNode = {
+  group: "nodes";
+  id: string;
+  data: {
+    id: string;
+    type: string;
+    /**
+     * Parent node (account, region etc)
+     */
+    parent?: string;
+    name?: string;
+    service?: string;
+  };
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  metadata?: any;
+};
+
+/**
+ * An edge connecting two nodes within a graph
+ */
+export type GraphEdge = {
+  group: "edges";
+  /**
+   * Unique ID for the edge
+   */
+  id?: string;
+  data: {
+    id: string;
+    name: string;
+    /**
+     * Source Node
+     */
+    source: string;
+    /**
+     * Target Node
+     */
+    target: string;
+    type: string;
+  };
+  metadata?: {
+    label: string;
+    roleArn?: string;
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    statement?: any;
+  };
+};
+
+/**
+ * Generic type for elements in a graph
+ */
+export type GraphElement = GraphNode | GraphEdge;
+
+export type EdgeTarget = {
+  name: string;
+  target: string;
+};

package/src/index.ts

@@ -0,0 +1,19 @@
+import {
+  GlobalServiceClients,
+  RegionalServiceClients,
+  ServiceClients,
+} from "./services";
+import type { GlobalService, RegionalService, Service } from "./services";
+
+export {
+  ServiceClients,
+  GlobalServiceClients,
+  RegionalServiceClients,
+  GlobalService,
+  RegionalService,
+  Service,
+};
+export * from "./api";
+export * from "./config";
+export * from "./graph";
+export * from "./scan";

package/src/scan.ts

@@ -0,0 +1,12 @@
+export type State<T> = {
+  _metadata: {
+    account: string;
+    region: string;
+  };
+  _result: T;
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  _parameters?: any;
+};
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type GenericState = State<any>;

package/src/services.ts

@@ -0,0 +1,64 @@
+import * as S3 from "@aws-sdk/client-s3";
+import * as CloudFront from "@aws-sdk/client-cloudfront";
+import * as Route53 from "@aws-sdk/client-route-53";
+
+import * as ApiGatewayV2 from "@aws-sdk/client-apigatewayv2";
+import * as AutoScaling from "@aws-sdk/client-auto-scaling";
+import * as CloudWatchLogs from "@aws-sdk/client-cloudwatch-logs";
+import * as DynamoDB from "@aws-sdk/client-dynamodb";
+import * as EC2 from "@aws-sdk/client-ec2";
+import * as ECS from "@aws-sdk/client-ecs";
+import * as ElasticLoadBalancingV2 from "@aws-sdk/client-elastic-load-balancing-v2";
+import * as Lambda from "@aws-sdk/client-lambda";
+import * as RDS from "@aws-sdk/client-rds";
+import * as SNS from "@aws-sdk/client-sns";
+import * as SQS from "@aws-sdk/client-sqs";
+
+/**
+ * Clients for Global Services
+ */
+export const GlobalServiceClients = {
+  S3,
+  CloudFront,
+  Route53,
+};
+
+/**
+ * Clients for Regional Services
+ */
+export const RegionalServiceClients = {
+  ApiGatewayV2,
+  AutoScaling,
+  CloudWatchLogs,
+  DynamoDB,
+  EC2,
+  ECS,
+  ElasticLoadBalancingV2,
+  Lambda,
+  RDS,
+  SNS,
+  SQS,
+};
+
+/**
+ * Clients for every service
+ */
+export const ServiceClients = {
+  ...GlobalServiceClients,
+  ...RegionalServiceClients,
+};
+
+/**
+ * Type for Global Services
+ */
+export type GlobalService = keyof typeof GlobalServiceClients;
+
+/**
+ * Type for Regional Services
+ */
+export type RegionalService = keyof typeof RegionalServiceClients;
+
+/**
+ * Type for any support service
+ */
+export type Service = GlobalService | RegionalService;

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "tsconfig/base.json",
+  "compilerOptions": {
+    "baseUrl": "src",
+    "noEmit": true,
+    "module": "Node16"
+  }
+}

package/typedoc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../typedoc.base.json"],
+  "entryPoints": ["src/index.ts"],
+}