@fabasoad/sarif-to-slack 0.2.4 → 1.0.0

package/src/representations/CompactGroupBySarifPerSeverityRepresentation.ts

@@ -0,0 +1,15 @@
+import CompactGroupBySarifRepresentation
+  from './CompactGroupBySarifRepresentation'
+
+/**
+ * Since {@link CompactGroupBySarifRepresentation} is an abstract class, the only
+ * question that this class should "answer" is what property should be used in
+ * the compact representation. In this case it is "severity".
+ * @internal
+ */
+export default class CompactGroupBySarifPerSeverityRepresentation extends CompactGroupBySarifRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('severity')
+  }
+}

package/src/representations/CompactGroupBySarifRepresentation.ts

@@ -0,0 +1,45 @@
+import path from 'node:path'
+import { Finding } from '../model/Finding'
+import CompactGroupByRepresentation from './CompactGroupByRepresentation'
+import { SarifModel } from '../types'
+
+/**
+ * Since {@link CompactGroupByRepresentation} already prepares compact representation
+ * of findings, this class defines a grouping rule. In this case it groups
+ * findings by SARIF file. Every SARIF file will be grouped separately, such as:
+ * @example
+ * ```text
+ * grype-results-01.sarif
+ * Error: 1, Warning: 4
+ * grype-results-02.sarif
+ * Warning: 1, Note: 20
+ * ```
+ * @internal
+ * It is an abstract class, so the only question that derived classes should
+ * "answer" is what property should be used in the compact representation, such
+ * as "level" and "severity".
+ */
+export default abstract class CompactGroupBySarifRepresentation extends CompactGroupByRepresentation {
+
+  public constructor(model: SarifModel) {
+    super(model, 'sarifPath')
+  }
+
+  protected override groupFindings(): Map<string, Finding[]> {
+    const result = new Map<string, Finding[]>()
+    for (let index = 0; index < this._model.sarifFiles.length; index++) {
+      const key: string = this.composeGroupTitle(this._model.sarifFiles[index], index)
+      if (result.get(key) == null) {
+        result.set(key, [])
+      }
+      this._model.findings
+        .filter((f: Finding): boolean => f.sarifPath === this._model.sarifFiles[index])
+        .forEach((f: Finding) => result.get(key)?.push(f))
+    }
+    return result
+  }
+
+  private composeGroupTitle(sarifPath: string, index: number): string {
+    return `${this.italic(`[File ${index + 1}]`)} ${this.bold(path.basename(sarifPath))}`
+  }
+}

package/src/representations/CompactGroupByToolNamePerLevelRepresentation.ts

@@ -0,0 +1,15 @@
+import CompactGroupByToolNameRepresentation
+  from './CompactGroupByToolNameRepresentation'
+
+/**
+ * Since {@link CompactGroupByToolNameRepresentation} is an abstract class, the
+ * only question that this class should "answer" is what property should be used
+ * in the compact representation. In this case it is "level".
+ * @internal
+ */
+export default class CompactGroupByToolNamePerLevelRepresentation extends CompactGroupByToolNameRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('level')
+  }
+}

package/src/representations/CompactGroupByToolNamePerSeverityRepresentation.ts

@@ -0,0 +1,15 @@
+import CompactGroupByToolNameRepresentation
+  from './CompactGroupByToolNameRepresentation'
+
+/**
+ * Since {@link CompactGroupByToolNameRepresentation} is an abstract class, the
+ * only question that this class should "answer" is what property should be used
+ * in the compact representation. In this case it is "severity".
+ * @internal
+ */
+export default class CompactGroupByToolNamePerSeverityRepresentation extends CompactGroupByToolNameRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('severity')
+  }
+}

package/src/representations/CompactGroupByToolNameRepresentation.ts

@@ -0,0 +1,44 @@
+import { Finding } from '../model/Finding'
+import CompactGroupByRepresentation from './CompactGroupByRepresentation'
+import { SarifModel } from '../types'
+
+/**
+ * Since {@link CompactGroupByRepresentation} already prepares compact representation
+ * of findings, this class defines a grouping rule. In this case it groups
+ * findings by tool name. Every tool name will be grouped separately, such as:
+ * @example
+ * ```text
+ * Grype
+ * Error: 1, Warning: 4
+ * Trivy
+ * Warning: 1, Note: 20
+ * ```
+ * @internal
+ * It is an abstract class, so the only question that derived classes should
+ * "answer" is what property should be used in the compact representation, such
+ * as "level" and "severity".
+ */
+export default abstract class CompactGroupByToolNameRepresentation extends CompactGroupByRepresentation {
+
+  public constructor(model: SarifModel) {
+    super(model, 'toolName')
+  }
+
+  protected override groupFindings(): Map<string, Finding[]> {
+    const result = new Map<string, Finding[]>()
+    for (const run of this._model.runs) {
+      const key: string = this.composeGroupTitle(run.toolName)
+      if (result.get(key) == null) {
+        result.set(key, [])
+      }
+      this._model.findings
+        .filter((f: Finding): boolean => f.runId === run.id)
+        .forEach((f: Finding) => result.get(key)?.push(f))
+    }
+    return result
+  }
+
+  private composeGroupTitle(toolName: string): string {
+    return this.bold(toolName)
+  }
+}

package/src/representations/CompactTotalPerLevelRepresentation.ts

@@ -0,0 +1,14 @@
+import CompactTotalRepresentation from './CompactTotalRepresentation'
+
+/**
+ * Since {@link CompactTotalRepresentation} is an abstract class, the only
+ * question that this class should "answer" is what property should be used in
+ * the compact representation. In this case it is "level".
+ * @internal
+ */
+export default class CompactTotalPerLevelRepresentation extends CompactTotalRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('level')
+  }
+}

package/src/representations/CompactTotalPerSeverityRepresentation.ts

@@ -0,0 +1,14 @@
+import CompactTotalRepresentation from './CompactTotalRepresentation'
+
+/**
+ * Since {@link CompactTotalRepresentation} is an abstract class, the only
+ * question that this class should "answer" is what property should be used in
+ * the compact representation. In this case it is "severity".
+ * @internal
+ */
+export default class CompactTotalPerSeverityRepresentation extends CompactTotalRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('severity')
+  }
+}

package/src/representations/CompactTotalRepresentation.ts

@@ -0,0 +1,27 @@
+import CompactGroupByRepresentation from './CompactGroupByRepresentation'
+import { Finding } from '../model/Finding'
+
+/**
+ * Since {@link CompactGroupByRepresentation} already prepares compact representation
+ * of findings, this class defines a grouping rule. In this case it does not really
+ * group, but just add everything under the same "Total" group, such as:
+ * @example
+ * ```text
+ * Total
+ * Warning: 1, Note: 20
+ * ```
+ * @internal
+ * It is an abstract class, so the only question that derived classes should
+ * "answer" is what property should be used in the compact representation, such
+ * as "level" and "severity".
+ */
+export default abstract class CompactTotalRepresentation extends CompactGroupByRepresentation {
+
+  protected override groupFindings(): Map<string, Finding[]> {
+    const result = new Map<string, Finding[]>()
+    if (this._model.findings.length > 0) {
+      result.set('Total', this._model.findings)
+    }
+    return result
+  }
+}

package/src/representations/Representation.ts

@@ -0,0 +1,35 @@
+import { SarifModel } from '../types'
+import { Finding } from '../model/Finding'
+import { findingsComparatorByKey } from '../utils/Comparators'
+import FindingsArray from '../model/FindingsArray'
+
+/**
+ * The most base abstract class for the representation. Every representation class
+ * must be derived from this class implicitly or explicitly.
+ * @internal
+ */
+export default abstract class Representation {
+  protected readonly _model: SarifModel
+
+  public constructor(model: SarifModel, findingSortKey: keyof Finding = 'level') {
+    this._model = model
+    this._model.findings = model
+      .findings
+      .map((f: Finding): Finding => f.clone())
+      .sort(findingsComparatorByKey(findingSortKey))
+      .reduce((arr: FindingsArray, f: Finding): FindingsArray => {
+        arr.push(f)
+        return arr
+      }, new FindingsArray())
+  }
+
+  protected bold(text: string): string {
+    return `*${text}*`
+  }
+
+  protected italic(text: string): string {
+    return `_${text}_`
+  }
+
+  abstract compose(): string
+}

package/src/representations/RepresentationFactory.ts

@@ -0,0 +1,49 @@
+import Representation from './Representation'
+import { RepresentationType, SarifModel } from '../types'
+import CompactGroupByRunPerLevelRepresentation
+  from './CompactGroupByRunPerLevelRepresentation'
+import CompactGroupByRunPerSeverityRepresentation
+  from './CompactGroupByRunPerSeverityRepresentation'
+import CompactGroupByToolNamePerLevelRepresentation
+  from './CompactGroupByToolNamePerLevelRepresentation'
+import CompactGroupByToolNamePerSeverityRepresentation
+  from './CompactGroupByToolNamePerSeverityRepresentation'
+import CompactGroupBySarifPerLevelRepresentation
+  from './CompactGroupBySarifPerLevelRepresentation'
+import CompactGroupBySarifPerSeverityRepresentation
+  from './CompactGroupBySarifPerSeverityRepresentation'
+import CompactTotalPerSeverityRepresentation
+  from './CompactTotalPerSeverityRepresentation'
+import CompactTotalPerLevelRepresentation
+  from './CompactTotalPerLevelRepresentation'
+
+/**
+ * Factory class that creates a {@link Representation} class based on the provided
+ * {@link RepresentationType}.
+ * @internal
+ */
+export function createRepresentation(
+  model: SarifModel,
+  type: RepresentationType = RepresentationType.CompactGroupByToolNamePerSeverity
+): Representation {
+  switch (type) {
+    case RepresentationType.CompactGroupByRunPerLevel:
+      return new CompactGroupByRunPerLevelRepresentation(model)
+    case RepresentationType.CompactGroupByRunPerSeverity:
+      return new CompactGroupByRunPerSeverityRepresentation(model)
+    case RepresentationType.CompactGroupByToolNamePerLevel:
+      return new CompactGroupByToolNamePerLevelRepresentation(model)
+    case RepresentationType.CompactGroupByToolNamePerSeverity:
+      return new CompactGroupByToolNamePerSeverityRepresentation(model)
+    case RepresentationType.CompactGroupBySarifPerLevel:
+      return new CompactGroupBySarifPerLevelRepresentation(model)
+    case RepresentationType.CompactGroupBySarifPerSeverity:
+      return new CompactGroupBySarifPerSeverityRepresentation(model)
+    case RepresentationType.CompactTotalPerLevel:
+      return new CompactTotalPerLevelRepresentation(model)
+    case RepresentationType.CompactTotalPerSeverity:
+      return new CompactTotalPerSeverityRepresentation(model)
+    default:
+      throw new Error(`Unknown representation type: ${type}`)
+  }
+}

package/src/types.ts

@@ -1,10 +1,6 @@
-import type { Log } from 'sarif'
-
-/**
- * Type representing a SARIF log.
- * @public
- */
-export type SarifLog = Log
+import { Run } from 'sarif'
+import { Color, ColorOptions } from './model/Color'
+import FindingsArray from './model/FindingsArray'
 
 /**
  * Interface for a Slack message that can be sent.
@@ -16,10 +12,10 @@ export interface SlackMessage {
    * @returns A promise that resolves to the response from the Slack webhook.
    */
   send: () => Promise<string>
-  /**
-   * The SARIF log associated with this Slack message.
-   */
-  sarif: SarifLog
+  withActor(actor?: string): void
+  withFooter(text?: string, type?: FooterType): void
+  withHeader(header?: string): void
+  withRun(): void
 }
 
 /**
@@ -107,86 +103,307 @@ export type FooterOptions = IncludeAwareWithValueOptions & {
 }
 
 /**
- * Enum representing how to group results.
+ * This represents what type of message should be sent. There are various options
+ * to show information from SARIF in Slack message.
  * @public
  */
-export enum GroupResultsBy {
+export enum RepresentationType {
+  /**
+   * Compact information about findings grouped by Run with the level representation.
+   * @example
+   * ```text
+   * [Run 1] Grype
+   * Error: 1, Warning: 4
+   * [Run 2] Grype
+   * Warning: 1, Note: 20
+   * ```
+   */
+  CompactGroupByRunPerLevel = 0,
+  /**
+   * Compact information about findings grouped by Run with the severity representation.
+   * @example
+   * ```text
+   * [Run 1] Grype
+   * Critical: 1, High: 3, Medium: 1
+   * [Run 2] Grype
+   * Medium: 1, Low: 20
+   * ```
+   */
+  CompactGroupByRunPerSeverity = 1,
+  /**
+   * Compact information about findings grouped by tool name with the level representation.
+   * @example
+   * ```text
+   * Grype
+   * Error: 1, Warning: 5, Note: 20
+   * ```
+   */
+  CompactGroupByToolNamePerLevel = 2,
   /**
-   * Groups results by the tool name. Particularly, groups by the runs[].tool.driver.name
-   * property from the SARIF file(s).
+   * Compact information about findings grouped by tool name with the severity representation.
+   * @example
+   * ```text
+   * Grype
+   * Critical: 1, High: 3, Medium: 2, Low: 20
+   * ```
    */
-  ToolName = 0,
+  CompactGroupByToolNamePerSeverity = 3,
   /**
-   * Groups results by the run. It provides the result from each run individually.
+   * Compact information about findings grouped by SARIF file with the level representation.
+   * @example
+   * ```text
+   * grype-results-01.sarif
+   * Error: 1, Warning: 2, Note: 1
+   * grype-results-02.sarif
+   * Warning: 3, Note: 19
+   * ```
    */
-  Run = 1,
+  CompactGroupBySarifPerLevel = 4,
   /**
-   * Does not group results. It provides the result from all the runs from all
-   * the provided SARIF files.
+   * Compact information about findings grouped by SARIF file with the severity
+   * representation.
+   * @example
+   * ```text
+   * grype-results-01.sarif
+   * High: 3, Medium: 1, Low: 11
+   * grype-results-02.sarif
+   * Critical: 1, Medium: 1, Low: 9
+   * ```
    */
-  Total = 2,
+  CompactGroupBySarifPerSeverity = 5,
+  /**
+   * Compact information about findings with the level representation.
+   * @example
+   * ```text
+   * Total
+   * Error: 1, Warning: 5, Note: 20
+   * ```
+   */
+  CompactTotalPerLevel = 6,
+  /**
+   * Compact information about findings with the severity representation.
+   * @example
+   * ```text
+   * Total
+   * Critical: 1, High: 3, Medium: 2, Low: 20
+   * ```
+   */
+  CompactTotalPerSeverity = 7,
 }
 
 /**
- * Enum representing how to calculate results.
+ * Options for logging.
  * @public
  */
-export enum CalculateResultsBy {
-  /**
-   * Calculates results by the security level of the findings: Error, Warning,
-   * Note and Unknown. At first, it tries to get the security level from runs[].results[].level
-   * property. If it is not defined, it tries to get the security level from the
-   * respective rule of each result, using the rules[].properties['problem.severity']
-   * property.
-   */
-  Level = 0,
+export type LogOptions = {
+  level?: LogLevel,
   /**
-   * Calculates results by the security severity of the findings: Critical, High,
-   * Medium, Low, None and Unknown. it tries to get the security severity from the
-   * respective rule of each result, using the rules[].properties['security-severity']
-   * property. This property contains CVSS score, which is then mapped to the
-   * security severity value.
+   * More details here: https://github.com/fullstack-build/tslog?tab=readme-ov-file#pretty-templates-and-styles-color-settings
    */
-  Severity = 1,
+  template?: string,
+  colored?: boolean,
 }
 
 /**
- * Options for how to output the results in the Slack message.
+ * SARIF file extension.
  * @public
  */
-export type SarifToSlackOutput = {
-  groupBy?: GroupResultsBy,
-  calculateBy?: CalculateResultsBy,
+export type SarifFileExtension = 'sarif' | 'json'
+
+/**
+ * Represents options for the provided SARIF file(s), such as path, should files
+ * from this path be retrieved recursively or not, and file extension.
+ * @public
+ */
+export type SarifOptions = {
+  path: string,
+  recursive?: boolean,
+  extension?: SarifFileExtension,
 }
 
 /**
- * Options for logging.
+ * This enum represents the condition on when message should be sent. If this
+ * condition is satisfied then message is sent, otherwise - message is not sent.
  * @public
  */
-export type LogOptions = {
-  level?: LogLevel,
+export enum SendIf {
   /**
-   * More details here: https://github.com/fullstack-build/tslog?tab=readme-ov-file#pretty-templates-and-styles-color-settings
+   * Send message only if there is at least one finding with "Critical" severity.
+   * Since it is the higher possible severity, it is the same as "Critical" or
+   * higher.
    */
-  template?: string,
-  colored?: boolean,
+  SeverityCritical,
+  /**
+   * Send message only if there is at least one finding with "High" severity.
+   */
+  SeverityHigh,
+  /**
+   * Send message only if there is at least one finding with "High" severity or
+   * higher, that includes "High" and "Critical".
+   */
+  SeverityHighOrHigher,
+  /**
+   * Send message only if there is at least one finding with "Medium" severity.
+   */
+  SeverityMedium,
+  /**
+   * Send message only if there is at least one finding with "Medium" severity
+   * or higher, that includes "Medium", "High" and "Critical".
+   */
+  SeverityMediumOrHigher,
+  /**
+   * Send message only if there is at least one finding with "Low" severity.
+   */
+  SeverityLow,
+  /**
+   * Send message only if there is at least one finding with "Low" severity or
+   * higher, that includes "Low", "Medium", "High" and "Critical".
+   */
+  SeverityLowOrHigher,
+  /**
+   * Send message only if there is at least one finding with "None" severity.
+   */
+  SeverityNone,
+  /**
+   * Send message only if there is at least one finding with "None" severity or
+   * higher, that includes "None", "Low", "Medium", "High" and "Critical".
+   */
+  SeverityNoneOrHigher,
+  /**
+   * Send message only if there is at least one finding with "Unknown" severity.
+   */
+  SeverityUnknown,
+  /**
+   * Send message only if there is at least one finding with "Unknown" severity
+   * or higher, that includes "Unknown", "None", "Low", "Medium", "High" and "Critical".
+   */
+  SeverityUnknownOrHigher,
+  /**
+   * Send message only if there is at least one finding with "Error" level.
+   * Since it is the higher possible level, it is the same as "Error" or higher.
+   */
+  LevelError,
+  /**
+   * Send message only if there is at least one finding with "Warning" level.
+   */
+  LevelWarning,
+  /**
+   * Send message only if there is at least one finding with "Warning" level or
+   * higher, that includes "Warning" and "Error".
+   */
+  LevelWarningOrHigher,
+  /**
+   * Send message only if there is at least one finding with "Note" level.
+   */
+  LevelNote,
+  /**
+   * Send message only if there is at least one finding with "Note" level or
+   * higher, that includes "Note", "Warning" and "Error.
+   */
+  LevelNoteOrHigher,
+  /**
+   * Send message only if there is at least one finding with "None" level.
+   */
+  LevelNone,
+  /**
+   * Send message only if there is at least one finding with "None" level or
+   * higher, that includes "None", "Note", "Warning" and "Error.
+   */
+  LevelNoneOrHigher,
+  /**
+   * Send message only if there is at least one finding with "Unknown" level.
+   */
+  LevelUnknown,
+  /**
+   * Send message only if there is at least one finding with "Unknown" level or
+   * higher, that includes "Unknown", "None", "Note", "Warning" and "Error.
+   */
+  LevelUnknownOrHigher,
+  /**
+   * Always send a message.
+   */
+  Always,
+  /**
+   * Send a message if at least 1 vulnerability is found.
+   */
+  Some,
+  /**
+   * Send a message only if no vulnerabilities are found.
+   */
+  Empty,
+  /**
+   * Never send a message.
+   */
+  Never,
 }
 
 /**
- * Options for the SarifToSlackService.
+ * Options for the SarifToSlackClient.
  * @public
  */
-export type SarifToSlackServiceOptions = {
-  // The Slack webhook URL to send messages to.
+export type SarifToSlackClientOptions = {
   webhookUrl: string,
-  sarifPath: string,
+  sarif: SarifOptions,
   username?: string,
   iconUrl?: string,
-  color?: string,
+  color?: Color | ColorOptions,
   log?: LogOptions,
   header?: IncludeAwareWithValueOptions,
   footer?: FooterOptions,
   actor?: IncludeAwareWithValueOptions,
   run?: IncludeAwareOptions,
-  output?: SarifToSlackOutput,
+  representation?: RepresentationType,
+  sendIf?: SendIf,
+}
+
+/**
+ * Enum of security severity.
+ * @privateRemarks Order should remain unchanged. It is used in multiple places,
+ * such as sorting in Slack message (more important come first) and to identify
+ * provided severity if it is requested severity or higher.
+ * @internal
+ */
+export enum SecuritySeverity {
+  Unknown = 0,
+  None = 1,
+  Low = 2,
+  Medium = 3,
+  High = 4,
+  Critical = 5,
+}
+
+/**
+ * Enum of security level.
+ * @privateRemarks Order should remain unchanged. It is used in multiple places,
+ * such as sorting in Slack message (more important come first) and to identify
+ * provided level if it is requested level or higher.
+ * @internal
+ */
+export enum SecurityLevel {
+  Unknown = 0,
+  None = 1,
+  Note = 2,
+  Warning = 3,
+  Error = 4,
+}
+
+/**
+ * The data about run, such as {@link Run} itself, tool name of the run and ID
+ * which is manually generated and unique within a single execution.
+ * @internal
+ */
+export type RunData = {
+  id: number,
+  run: Run,
+  toolName: string,
+}
+
+/**
+ * Model that is used by {@link Representation}
+ * @internal
+ */
+export type SarifModel = {
+  sarifFiles: string[],
+  runs: RunData[],
+  findings: FindingsArray,
 }

package/src/utils/Comparators.ts

@@ -0,0 +1,19 @@
+import { Finding } from '../model/Finding'
+
+/**
+ * This function returns a comparator function based on the property of the
+ * {@link Finding} object.
+ * @param key Property name of the {@link Finding} object.
+ * @internal
+ */
+export function findingsComparatorByKey<K extends keyof Finding>(key: K): (a: Finding, b: Finding) => number {
+  return (a: Finding, b: Finding): number => {
+    switch (key) {
+      case 'severity': return b.severity - a.severity
+      case 'level': return b.level - a.level
+      case 'runId': return a.runId - b.runId
+      case 'toolName': return a.toolName.toLowerCase().localeCompare(b.toolName.toLowerCase())
+      default: return 1
+    }
+  }
+}