@fabasoad/sarif-to-slack 1.0.0 → 1.2.0

package/src/model/Color.ts

@@ -1,6 +1,6 @@
 import { SecurityLevel, SecuritySeverity } from '../types'
-import { Finding } from './Finding'
-import FindingsArray from './FindingsArray'
+import Finding from './Finding'
+import FindingArray from './FindingArray'
 
 /**
  * This class represents a color in hex format.
@@ -20,7 +20,7 @@ export class Color {
    */
   public constructor(color?: string) {
     this._color = this.mapColor(color)
-    this.validateHexColor()
+    this.assertHexColor()
   }
 
   /**
@@ -30,7 +30,7 @@ export class Color {
     return this._color
   }
 
-  private validateHexColor(): void {
+  private assertHexColor(): void {
     if (this._color != null) {
       const hexColorRegex = /^#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
 
@@ -64,7 +64,6 @@ export class Color {
 type ColorGroupCommon = {
   none?: Color,
   unknown?: Color,
-  empty?: Color,
 }
 
 /**
@@ -95,30 +94,37 @@ export type ColorGroupBySeverity = ColorGroupCommon & {
 }
 
 /**
- * Represents configuration of the color scheme. {@link ColorOptions.byLevel} has
- * color scheme for the findings where certain level presented. {@link ColorOptions.bySeverity}
- * has color scheme for the findings where certain severity presented.
+ * Represents configuration of the color scheme. If both {@link ColorOptions.byLevel}
+ * and {@link ColorOptions.bySeverity} are defined, then {@link ColorOptions.bySeverity}
+ * takes precedence.
  * @public
  */
 export type ColorOptions = {
+  /**
+   * Default color if specific color was not found. It is a fallback option.
+   */
+  default?: Color,
+  /**
+   * Color scheme for the findings where certain level is presented.
+   */
   byLevel?: ColorGroupByLevel,
+  /**
+   * Color scheme for the findings where certain severity is presented.
+   */
   bySeverity?: ColorGroupBySeverity,
-}
-
-function isColor(color?: Color | ColorOptions): color is Color {
-  return color != null && color instanceof Color
-}
-
-function isColorOptions(color?: Color | ColorOptions): color is ColorOptions {
-  return color != null
+  /**
+   * Color when no findings are found.
+   */
+  empty?: Color,
 }
 
 function identifyColorCommon<K extends keyof Finding>(
-  findings: FindingsArray,
+  findings: FindingArray,
   prop: K,
   none: Finding[K],
   unknown: Finding[K],
-  color: ColorGroupCommon
+  color: ColorGroupCommon,
+  defaultColor?: Color
 ): string | undefined {
   if (color.none != null && findings.findByProperty(prop, none) != null) {
     return color.none.value
@@ -128,14 +134,10 @@ function identifyColorCommon<K extends keyof Finding>(
     return color.unknown.value
   }
 
-  if (color.empty != null && findings.length === 0) {
-    return color.empty.value
-  }
-
-  return undefined
+  return defaultColor?.value
 }
 
-function identifyColorBySeverity(findings: FindingsArray, color: ColorGroupBySeverity): string | undefined {
+function identifyColorBySeverity(findings: FindingArray, color: ColorGroupBySeverity, defaultColor?: Color): string | undefined {
   if (color.critical != null && findings.findByProperty('severity', SecuritySeverity.Critical) != null) {
     return color.critical.value
   }
@@ -152,10 +154,10 @@ function identifyColorBySeverity(findings: FindingsArray, color: ColorGroupBySev
     return color.low.value
   }
 
-  return identifyColorCommon(findings, 'severity', SecuritySeverity.None, SecuritySeverity.Unknown, color)
+  return identifyColorCommon(findings, 'severity', SecuritySeverity.None, SecuritySeverity.Unknown, color, defaultColor)
 }
 
-function identifyColorByLevel(findings: FindingsArray, color: ColorGroupByLevel): string | undefined {
+function identifyColorByLevel(findings: FindingArray, color: ColorGroupByLevel, defaultColor?: Color): string | undefined {
   if (color.error != null && findings.findByProperty('level', SecurityLevel.Error) != null) {
     return color.error.value
   }
@@ -168,34 +170,29 @@ function identifyColorByLevel(findings: FindingsArray, color: ColorGroupByLevel)
     return color.note.value
   }
 
-  return identifyColorCommon(findings, 'level', SecurityLevel.None, SecurityLevel.Unknown, color)
+  return identifyColorCommon(findings, 'level', SecurityLevel.None, SecurityLevel.Unknown, color, defaultColor)
 }
 
 /**
  * Makes an ultimate decision on what color should be Slack message. The decision
- * is based on the provided {@param color} parameter and {@param findings} list.
- * @param findings An instance of {@link FindingsArray} object.
- * @param color Either an instance of {@link Color} or {@link ColorOptions} type.
+ * is based on the provided {@param colorOpts} parameter and {@param findings}
+ * list.
+ * @param findings An instance of {@link FindingArray} object.
+ * @param colorOpts An instance of {@link ColorOptions} type.
  * @internal
  */
-export function identifyColor(findings: FindingsArray, color?: Color | ColorOptions): string | undefined {
-  if (color == null) {
-    return undefined
-  }
+export function identifyColor(findings: FindingArray, colorOpts?: ColorOptions): string | undefined {
+  let result: string | undefined = colorOpts?.bySeverity
+    ? identifyColorBySeverity(findings, colorOpts.bySeverity, colorOpts.default)
+    : undefined
 
-  if (isColor(color)) {
-    return color.value
-  }
+  result ??= colorOpts?.byLevel
+    ? identifyColorByLevel(findings, colorOpts.byLevel, colorOpts.default)
+    : result
 
-  if (isColorOptions(color)) {
-    if (color.bySeverity != null) {
-      return identifyColorBySeverity(findings, color.bySeverity)
-    }
+  result ??= findings.length === 0 ? colorOpts?.empty?.value : result
 
-    if (color.byLevel != null) {
-      return identifyColorByLevel(findings, color.byLevel)
-    }
-  }
+  result ??= colorOpts?.default?.value
 
-  return undefined
+  return result
 }

package/src/model/Finding.ts

@@ -18,7 +18,7 @@ export type FindingOptions = {
  * This interface represents a finding from SARIF file.
  * @internal
  */
-export interface Finding {
+export default interface Finding {
   get sarifPath(): string,
   get runId(): number,
   get toolName(): string,
@@ -33,7 +33,7 @@ export interface Finding {
  * @internal
  */
 export function createFinding(opts: FindingOptions): Finding {
-  return new SarifFinding(opts)
+  return new FindingImpl(opts)
 }
 
 /**
@@ -42,7 +42,7 @@ export function createFinding(opts: FindingOptions): Finding {
  * create a new {@link Finding}.
  * @private
  */
-class SarifFinding implements Finding {
+class FindingImpl implements Finding {
   private readonly _runMetadata: RunData
   private readonly _result: Result
   private readonly _sarifPath: string

package/src/model/{FindingsArray.ts → FindingArray.ts}

@@ -1,13 +1,13 @@
-import { Finding } from './Finding'
-import ExtendedArray from '../utils/ExtendedArray'
+import Finding from './Finding'
 import { SecurityLevel, SecuritySeverity } from '../types'
+import ExtendedArray from '../utils/ExtendedArray'
 
 /**
  * This class represents an array of {@link Finding} objects and adds additional
  * useful methods to it.
  * @internal
  */
-export default class FindingsArray extends ExtendedArray<Finding> {
+export default class FindingArray extends ExtendedArray<Finding> {
 
   public hasSeverityOrHigher(severity: SecuritySeverity): boolean {
     return Object

package/src/model/SendIf.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 enum SendIf {
+  /**
+   * 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.
+   */
+  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,
+}
+
+/**
+ * Returns log message based on the provided {@param sendIf} parameter.
+ * @param sendIf An instance of {@link SendIf} enum.
+ * @internal
+ */
+export function sendIfLogMessage(sendIf: SendIf): string {
+  switch (sendIf) {
+    case SendIf.SeverityCritical:
+      return 'No message sent: no findings with "Critical" severity.'
+    case SendIf.SeverityHigh:
+      return 'No message sent: no findings with "High" severity.'
+    case SendIf.SeverityHighOrHigher:
+      return 'No message sent: no findings with "High" or higher severity.'
+    case SendIf.SeverityMedium:
+      return 'No message sent: no findings with "Medium" severity.'
+    case SendIf.SeverityMediumOrHigher:
+      return 'No message sent: no findings with "Medium" or higher severity.'
+    case SendIf.SeverityLow:
+      return 'No message sent: no findings with "Low" severity.'
+    case SendIf.SeverityLowOrHigher:
+      return 'No message sent: no findings with "Low" or higher severity.'
+    case SendIf.SeverityNone:
+      return 'No message sent: no findings with "None" severity.'
+    case SendIf.SeverityNoneOrHigher:
+      return 'No message sent: no findings with "None" or higher severity.'
+    case SendIf.SeverityUnknown:
+      return 'No message sent: no findings with "Unknown" severity.'
+    case SendIf.SeverityUnknownOrHigher:
+      return 'No message sent: no findings with "Unknown" or higher severity.'
+    case SendIf.LevelError:
+      return 'No message sent: no findings with "Error" level.'
+    case SendIf.LevelWarning:
+      return 'No message sent: no findings with "Warning" level.'
+    case SendIf.LevelWarningOrHigher:
+      return 'No message sent: no findings with "Warning" or higher level.'
+    case SendIf.LevelNote:
+      return 'No message sent: no findings with "Note" level.'
+    case SendIf.LevelNoteOrHigher:
+      return 'No message sent: no findings with "Note" or higher level.'
+    case SendIf.LevelNone:
+      return 'No message sent: no findings with "None" level.'
+    case SendIf.LevelNoneOrHigher:
+      return 'No message sent: no findings with "None" or higher level.'
+    case SendIf.LevelUnknown:
+      return 'No message sent: no findings with "Unknown" level.'
+    case SendIf.LevelUnknownOrHigher:
+      return 'No message sent: no findings with "Unknown" or higher level.'
+    case SendIf.Always:
+      return 'Message always sent.'
+    case SendIf.Some:
+      return 'No message sent: findings are not found.'
+    case SendIf.Empty:
+      return 'No message sent: some findings are found.'
+    case SendIf.Never:
+      return 'No message sent: sending is disabled.'
+    default:
+      return 'Unknown SendIf value.'
+  }
+}

package/src/{SlackMessageBuilder.ts → model/SlackMessage.ts}

@@ -2,26 +2,51 @@ import { AnyBlock } from '@slack/types'
 import { ContextBlock, HeaderBlock } from '@slack/types/dist/block-kit/blocks'
 import { TextObject } from '@slack/types/dist/block-kit/composition-objects'
 import { IncomingWebhook } from '@slack/webhook'
-import { FooterType, SlackMessage } from './types'
-import { version } from './metadata.json'
-import Representation from './representations/Representation'
+import { FooterType } from '../types'
+import Representation from '../representations/Representation'
+import { version } from '../metadata.json'
 
 /**
  * Options for the SlackMessageBuilder.
  * @internal
  */
-export type SlackMessageBuilderOptions = {
+export type SlackMessageOptions = {
   username?: string
   iconUrl?: string
   color?: string
   representation: Representation,
 }
 
+/**
+ * Interface for a Slack message that can be sent.
+ * @public
+ */
+export interface SlackMessage {
+  /**
+   * Sends the Slack message.
+   * @returns A promise that resolves to the response from the Slack webhook.
+   */
+  send: () => Promise<string>
+  withActor(actor?: string): void
+  withFooter(text?: string, type?: FooterType): void
+  withHeader(header?: string): void
+  withRun(): void
+}
+
+/**
+ * Creates a new instance of {@link SlackMessage} class.
+ * @param url Slack webhook URL
+ * @param opts An instance of {@link SlackMessageOptions} type.
+ */
+export function createSlackMessage(url: string, opts: SlackMessageOptions): SlackMessage {
+  return new SlackMessageImpl(url, opts)
+}
+
 /**
  * Class for building and sending Slack messages based on SARIF logs.
  * @internal
  */
-export class SlackMessageBuilder implements SlackMessage {
+class SlackMessageImpl implements SlackMessage {
   private readonly _webhook: IncomingWebhook
   private readonly _gitHubServerUrl: string
   private readonly _color?: string
@@ -32,7 +57,7 @@ export class SlackMessageBuilder implements SlackMessage {
   private _actor?: string
   private _runId?: string
 
-  constructor(url: string, opts: SlackMessageBuilderOptions) {
+  constructor(url: string, opts: SlackMessageOptions) {
     this._webhook = new IncomingWebhook(url, {
       username: opts.username || 'SARIF results',
       icon_url: opts.iconUrl

package/src/processors/CodeQLProcessor.ts

@@ -1,5 +1,5 @@
 import { CommonProcessor } from './CommonProcessor'
-import { Result } from 'sarif';
+import { Result } from 'sarif'
 
 /**
  * This class has extra logic for processing SARIF files produced by CodeQL tool.

package/src/representations/CompactGroupByRepresentation.ts

@@ -1,5 +1,5 @@
 import Representation from './Representation'
-import { Finding } from '../model/Finding'
+import Finding from '../model/Finding'
 import { findingsComparatorByKey } from '../utils/Comparators'
 import { SecurityLevel, SecuritySeverity } from '../types';
 

package/src/representations/CompactGroupByRunRepresentation.ts

@@ -1,4 +1,4 @@
-import { Finding } from '../model/Finding'
+import Finding from '../model/Finding'
 import CompactGroupByRepresentation from './CompactGroupByRepresentation'
 import { SarifModel } from '../types'
 

package/src/representations/CompactGroupBySarifRepresentation.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import { Finding } from '../model/Finding'
+import Finding from '../model/Finding'
 import CompactGroupByRepresentation from './CompactGroupByRepresentation'
 import { SarifModel } from '../types'
 

package/src/representations/CompactGroupByToolNameRepresentation.ts

@@ -1,4 +1,4 @@
-import { Finding } from '../model/Finding'
+import Finding from '../model/Finding'
 import CompactGroupByRepresentation from './CompactGroupByRepresentation'
 import { SarifModel } from '../types'
 

package/src/representations/CompactTotalRepresentation.ts

@@ -1,5 +1,5 @@
 import CompactGroupByRepresentation from './CompactGroupByRepresentation'
-import { Finding } from '../model/Finding'
+import Finding from '../model/Finding'
 
 /**
  * Since {@link CompactGroupByRepresentation} already prepares compact representation

package/src/representations/Representation.ts

@@ -1,7 +1,7 @@
 import { SarifModel } from '../types'
-import { Finding } from '../model/Finding'
+import Finding from '../model/Finding'
 import { findingsComparatorByKey } from '../utils/Comparators'
-import FindingsArray from '../model/FindingsArray'
+import FindingArray from '../model/FindingArray'
 
 /**
  * The most base abstract class for the representation. Every representation class
@@ -17,10 +17,10 @@ export default abstract class Representation {
       .findings
       .map((f: Finding): Finding => f.clone())
       .sort(findingsComparatorByKey(findingSortKey))
-      .reduce((arr: FindingsArray, f: Finding): FindingsArray => {
+      .reduce((arr: FindingArray, f: Finding): FindingArray => {
         arr.push(f)
         return arr
-      }, new FindingsArray())
+      }, new FindingArray())
   }
 
   protected bold(text: string): string {

package/src/types.ts

@@ -1,22 +1,7 @@
 import { Run } from 'sarif'
-import { Color, ColorOptions } from './model/Color'
-import FindingsArray from './model/FindingsArray'
-
-/**
- * Interface for a Slack message that can be sent.
- * @public
- */
-export interface SlackMessage {
-  /**
-   * Sends the Slack message.
-   * @returns A promise that resolves to the response from the Slack webhook.
-   */
-  send: () => Promise<string>
-  withActor(actor?: string): void
-  withFooter(text?: string, type?: FooterType): void
-  withHeader(header?: string): void
-  withRun(): void
-}
+import { ColorOptions } from './model/Color'
+import FindingArray from './model/FindingArray'
+import { SendIf } from './model/SendIf'
 
 /**
  * Enum representing log levels for the service.
@@ -221,122 +206,6 @@ export type SarifOptions = {
   extension?: SarifFileExtension,
 }
 
-/**
- * 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 enum SendIf {
-  /**
-   * 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.
-   */
-  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 SarifToSlackClient.
  * @public
@@ -346,7 +215,7 @@ export type SarifToSlackClientOptions = {
   sarif: SarifOptions,
   username?: string,
   iconUrl?: string,
-  color?: Color | ColorOptions,
+  color?: ColorOptions,
   log?: LogOptions,
   header?: IncludeAwareWithValueOptions,
   footer?: FooterOptions,
@@ -405,5 +274,5 @@ export type RunData = {
 export type SarifModel = {
   sarifFiles: string[],
   runs: RunData[],
-  findings: FindingsArray,
+  findings: FindingArray,
 }