@fabasoad/sarif-to-slack 0.2.5 → 1.1.0

package/src/model/Color.ts

@@ -0,0 +1,195 @@
+import { SecurityLevel, SecuritySeverity } from '../types'
+import { Finding } from './Finding'
+import FindingsArray from './FindingsArray'
+
+/**
+ * This class represents a color in hex format.
+ * @public
+ */
+export class Color {
+  private readonly _color?: string
+
+  /**
+   * Creates an instance of {@link Color} class. Before creating an instance of
+   * {@link Color} class, it (if applicable) maps CI status into the hex color,
+   * and also validates {@param color} to be a valid string that represents a
+   * color in hex format.
+   * @param color Can be either undefined, valid color in hex format or GitHub
+   * CI status (one of: success, failure, cancelled, skipped)
+   * @public
+   */
+  public constructor(color?: string) {
+    this._color = this.mapColor(color)
+    this.validateHexColor()
+  }
+
+  /**
+   * Returns a valid string that represents a color in hex format, or undefined.
+   */
+  public get value(): string | undefined {
+    return this._color
+  }
+
+  private validateHexColor(): 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})$/;
+
+      if (!hexColorRegex.test(this._color)) {
+        throw new Error(`Invalid hex color: "${this._color}"`);
+      }
+    }
+  }
+
+  private mapColor(from?: string): string | undefined {
+    switch (from) {
+      case 'success':
+        return '#008000'
+      case 'failure':
+        return '#ff0000'
+      case 'cancelled':
+        return '#0047ab'
+      case 'skipped':
+        return '#808080'
+      default:
+        return from
+    }
+  }
+}
+
+/**
+ * Base type that has common fields for both {@link ColorGroupByLevel} and
+ * {@link ColorGroupBySeverity}.
+ * @private
+ */
+type ColorGroupCommon = {
+  none?: Color,
+  unknown?: Color,
+  empty?: Color,
+}
+
+/**
+ * Color schema for the findings with the certain level. Color is used by the
+ * level importance, i.e. if at least 1 error finding exists then
+ * {@link ColorGroupByLevel.error} color is used, then if at least 1 warning
+ * finding exists then {@link ColorGroupByLevel.warning} color is used, etc.
+ * @public
+ */
+export type ColorGroupByLevel = ColorGroupCommon & {
+  error?: Color,
+  warning?: Color,
+  note?: Color,
+}
+
+/**
+ * Color schema for the findings with the certain severity. Color is used by the
+ * severity importance, i.e. if at least 1 critical finding exists then
+ * {@link ColorGroupBySeverity.critical} color is used, then if at least 1 high
+ * finding exists then {@link ColorGroupBySeverity.high} color is used, etc.
+ * @public
+ */
+export type ColorGroupBySeverity = ColorGroupCommon & {
+  critical?: Color,
+  high?: Color,
+  medium?: Color,
+  low?: Color,
+}
+
+/**
+ * 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 identifyColorCommon<K extends keyof Finding>(
+  findings: FindingsArray,
+  prop: K,
+  none: Finding[K],
+  unknown: Finding[K],
+  color: ColorGroupCommon,
+  defaultColor?: Color
+): string | undefined {
+  if (color.none != null && findings.findByProperty(prop, none) != null) {
+    return color.none.value
+  }
+
+  if (color.unknown != null && findings.findByProperty(prop, unknown) != null) {
+    return color.unknown.value
+  }
+
+  if (color.empty != null && findings.length === 0) {
+    return color.empty.value
+  }
+
+  return defaultColor?.value
+}
+
+function identifyColorBySeverity(findings: FindingsArray, color: ColorGroupBySeverity, defaultColor?: Color): string | undefined {
+  if (color.critical != null && findings.findByProperty('severity', SecuritySeverity.Critical) != null) {
+    return color.critical.value
+  }
+
+  if (color.high != null && findings.findByProperty('severity', SecuritySeverity.High) != null) {
+    return color.high.value
+  }
+
+  if (color.medium != null && findings.findByProperty('severity', SecuritySeverity.Medium) != null) {
+    return color.medium.value
+  }
+
+  if (color.low != null && findings.findByProperty('severity', SecuritySeverity.Low) != null) {
+    return color.low.value
+  }
+
+  return identifyColorCommon(findings, 'severity', SecuritySeverity.None, SecuritySeverity.Unknown, color, defaultColor)
+}
+
+function identifyColorByLevel(findings: FindingsArray, color: ColorGroupByLevel, defaultColor?: Color): string | undefined {
+  if (color.error != null && findings.findByProperty('level', SecurityLevel.Error) != null) {
+    return color.error.value
+  }
+
+  if (color.warning != null && findings.findByProperty('level', SecurityLevel.Warning) != null) {
+    return color.warning.value
+  }
+
+  if (color.note != null && findings.findByProperty('level', SecurityLevel.Note) != null) {
+    return color.note.value
+  }
+
+  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 colorOpts} parameter and {@param findings}
+ * list.
+ * @param findings An instance of {@link FindingsArray} object.
+ * @param colorOpts An instance of {@link ColorOptions} type.
+ * @internal
+ */
+export function identifyColor(findings: FindingsArray, colorOpts?: ColorOptions): string | undefined {
+  if (colorOpts?.bySeverity != null) {
+    return identifyColorBySeverity(findings, colorOpts.bySeverity, colorOpts.default)
+  }
+
+  if (colorOpts?.byLevel != null) {
+    return identifyColorByLevel(findings, colorOpts.byLevel, colorOpts.default)
+  }
+
+  return colorOpts?.default?.value
+}

package/src/model/Finding.ts

@@ -0,0 +1,137 @@
+import type { ReportingDescriptor, Result } from 'sarif'
+import { RunData, SecurityLevel, SecuritySeverity } from '../types'
+import Logger from '../Logger'
+import { CommonProcessor } from '../processors/CommonProcessor'
+import { createProcessor } from '../processors/ProcessorFactory'
+
+/**
+ * Parameters that are needed for the new {@link Finding} instance creation.
+ * @internal
+ */
+export type FindingOptions = {
+  sarifPath: string,
+  runMetadata: RunData,
+  result: Result,
+}
+
+/**
+ * This interface represents a finding from SARIF file.
+ * @internal
+ */
+export interface Finding {
+  get sarifPath(): string,
+  get runId(): number,
+  get toolName(): string,
+  get cvssScore(): number | undefined,
+  get level(): SecurityLevel,
+  get severity(): SecuritySeverity,
+  clone(): Finding,
+}
+
+/**
+ * Creates a new instance of {@link Finding} class.
+ * @internal
+ */
+export function createFinding(opts: FindingOptions): Finding {
+  return new SarifFinding(opts)
+}
+
+/**
+ * The only implementation of {@link Finding} interface. This class is private
+ * and is not supposed to be exposed. {@link createFinding} should be used to
+ * create a new {@link Finding}.
+ * @private
+ */
+class SarifFinding implements Finding {
+  private readonly _runMetadata: RunData
+  private readonly _result: Result
+  private readonly _sarifPath: string
+  private readonly _rule?: ReportingDescriptor
+  private readonly _processor: CommonProcessor
+
+  private _cvssScoreCacheProcessed: boolean = false
+  private _cvssScoreCache: number | undefined = undefined
+
+  private _levelCacheProcessed: boolean = false
+  private _levelCache: Result.level | undefined = undefined
+
+  constructor(opts: FindingOptions) {
+    this._processor = createProcessor(opts.runMetadata.run, opts.result)
+    this._sarifPath = opts.sarifPath
+    this._runMetadata = opts.runMetadata
+    this._result = opts.result
+    this._rule = this._processor.tryFindRule()
+  }
+
+  clone(): Finding {
+    return createFinding({
+      sarifPath: this._sarifPath,
+      runMetadata: this._runMetadata,
+      result: this._result
+    })
+  }
+
+  public get sarifPath(): string {
+    return this._sarifPath
+  }
+
+  public get runId(): number {
+    return this._runMetadata.id
+  }
+
+  public get toolName(): string {
+    return this._processor.findToolComponent().name
+  }
+
+  public get cvssScore(): number | undefined {
+    if (!this._cvssScoreCacheProcessed) {
+      this._cvssScoreCacheProcessed = true
+      this._cvssScoreCache = this._processor.tryFindCvssScore()
+    }
+    return this._cvssScoreCache
+  }
+
+  public get level(): SecurityLevel {
+    if (!this._levelCacheProcessed) {
+      this._levelCacheProcessed = true
+      this._levelCache = this._processor.tryFindLevel()
+    }
+
+    if (this._levelCache === undefined) {
+      Logger.debug(`Unknown level of ${this._rule?.id} rule`)
+      return SecurityLevel.Unknown
+    }
+
+    switch (this._levelCache) {
+      case 'error': return SecurityLevel.Error
+      case 'warning': return SecurityLevel.Warning
+      case 'note': return SecurityLevel.Note
+      default: return SecurityLevel.None
+    }
+  }
+
+  public get severity(): SecuritySeverity {
+    if (this.cvssScore == null || this.cvssScore < 0 || this.cvssScore > 10) {
+      Logger.debug(`Unsupported CVSS score ${this.cvssScore} in ${this._rule?.id} rule`)
+      return SecuritySeverity.Unknown
+    }
+
+    if (this.cvssScore >= 9) {
+      return SecuritySeverity.Critical
+    }
+
+    if (this.cvssScore >= 7) {
+      return SecuritySeverity.High
+    }
+
+    if (this.cvssScore >= 4) {
+      return SecuritySeverity.Medium
+    }
+
+    if (this.cvssScore >= 0.1) {
+      return SecuritySeverity.Low
+    }
+
+    return SecuritySeverity.None
+  }
+}

package/src/model/FindingsArray.ts

@@ -0,0 +1,27 @@
+import { Finding } from './Finding'
+import ExtendedArray from '../utils/ExtendedArray'
+import { SecurityLevel, SecuritySeverity } from '../types'
+
+/**
+ * This class represents an array of {@link Finding} objects and adds additional
+ * useful methods to it.
+ * @internal
+ */
+export default class FindingsArray extends ExtendedArray<Finding> {
+
+  public hasSeverityOrHigher(severity: SecuritySeverity): boolean {
+    return Object
+      .values(SecuritySeverity)
+      .filter((v: string | SecuritySeverity): v is SecuritySeverity => typeof v === 'number')
+      .filter((v: SecuritySeverity): boolean => v >= severity)
+      .some((v: SecuritySeverity): boolean => this.findByProperty('severity', v) != null)
+  }
+
+  public hasLevelOrHigher(level: SecurityLevel): boolean {
+    return Object
+      .values(SecurityLevel)
+      .filter((v: string | SecurityLevel): v is SecurityLevel => typeof v === 'number')
+      .filter((v: SecurityLevel): boolean => v >= level)
+      .some((v: SecurityLevel): boolean => this.findByProperty('level', v) != null)
+  }
+}

package/src/processors/CodeQLProcessor.ts

@@ -0,0 +1,19 @@
+import { CommonProcessor } from './CommonProcessor'
+import { Result } from 'sarif';
+
+/**
+ * This class has extra logic for processing SARIF files produced by CodeQL tool.
+ * @internal
+ */
+export class CodeQLProcessor extends CommonProcessor {
+
+  /**
+   * Rules in SARIF files produced by CodeQL has additional "problem.severity"
+   * property where level is also defined. This method tries to get level in a
+   * common way but if it fails to do so, then it tries to get level from
+   * "problem.severity" property.
+   */
+  public override tryFindLevel(): Result.level | undefined {
+    return super.tryFindLevel() ?? this.tryFindRuleProperty('problem.severity')
+  }
+}

package/src/processors/CommonProcessor.ts

@@ -0,0 +1,103 @@
+import type { ReportingDescriptor, Result, Run, ToolComponent } from 'sarif'
+import * as sarifUtils from '../utils/SarifUtils'
+
+/**
+ * This class has logic of the SARIF file processing, such as finding rule,
+ * finding tool component, etc. It is used by default for all SARIF files.
+ * Derived classes from this class can implement extra logic for the specific
+ * use cases, such as SARIF files produced by specific tools. For example,
+ * {@link CodeQLProcessor} handles additional logic for processing SARIF files
+ * produced by CodeQL.
+ * @internal
+ */
+export class CommonProcessor {
+  protected readonly _run: Run
+  protected readonly _result: Result
+
+  /**
+   * Creates an instance of {@link CommonProcessor} class.
+   * @param run An instance of {@link Run} object.
+   * @param result An instance of {@link Result} object.
+   */
+  public constructor(run: Run, result: Result) {
+    this._run = run
+    this._result = result
+  }
+
+  public tryFindCvssScore(): number | undefined {
+    return this.tryFindRuleProperty('security-severity')
+  }
+
+  public tryFindLevel(): Result.level | undefined {
+    return this._result.level ?? this.tryFindRule()?.defaultConfiguration?.level
+  }
+
+  public findToolComponentDriver(): ToolComponent {
+    return sarifUtils.findToolComponentDriver(this._run)
+  }
+
+  public tryFindToolComponentExtension(): ToolComponent | undefined {
+    return sarifUtils.tryFindToolComponentExtension(this._run, this._result)
+  }
+
+  public findToolComponent(): ToolComponent {
+    return sarifUtils.findToolComponent(this._run, this._result)
+  }
+
+  /**
+   * This function tries to find the respective rule for the given result.
+   * @internal
+   */
+  public tryFindRule(): ReportingDescriptor | undefined {
+    const ruleData: { id?: string, index?: number } = {}
+
+    if (this._result.rule) {
+      if (this._result.rule?.index != null) {
+        ruleData.index = this._result.rule.index
+      }
+      if (this._result.rule?.id) {
+        ruleData.id = this._result.rule.id
+      }
+    }
+
+    if (ruleData.index == null && this._result.ruleIndex != null) {
+      ruleData.index = this._result.ruleIndex
+    }
+
+    if (!ruleData.id && this._result.ruleId) {
+      ruleData.id = this._result.ruleId
+    }
+
+    const tool: ToolComponent = this.findToolComponent()
+
+    if (ruleData.index != null
+      && tool?.rules
+      && ruleData.index < tool.rules.length) {
+      return tool.rules[ruleData.index]
+    }
+
+    // If failed to find rule by index then try to find by ruleId
+    if (ruleData.id && tool?.rules) {
+      return tool.rules.find(
+        (r: ReportingDescriptor): boolean => r.id === ruleData.id
+      )
+    }
+
+    return undefined
+  }
+
+  /**
+   * This function searches respective rule for the given result, and then gets
+   * the property of interest from it.
+   * @param propertyName The property name that you want to get the value from.
+   * @protected
+   */
+  protected tryFindRuleProperty<T>(propertyName: string): T | undefined {
+    const rule: ReportingDescriptor | undefined = this.tryFindRule()
+    if (rule?.properties && propertyName in rule.properties) {
+      return rule.properties[propertyName] as T
+    }
+
+    return undefined
+  }
+}

package/src/processors/ProcessorFactory.ts

@@ -0,0 +1,23 @@
+import { CommonProcessor } from './CommonProcessor'
+import type { Result, Run, ToolComponent } from 'sarif'
+import { findToolComponent } from '../utils/SarifUtils'
+import { SnykProcessor } from './SnykProcessor'
+import { CodeQLProcessor } from './CodeQLProcessor'
+
+/**
+ * Creates a new instance of {@link CommonProcessor} class. It tries to find specific
+ * processor based on the tool component for the given {@param run} and
+ * {@param result} and if no specific processors exist, then it returns an
+ * instance of {@link CommonProcessor} class.
+ * @param run An instance of {@link Run} class.
+ * @param result An instance of {@link Result} class.
+ * @internal
+ */
+export function createProcessor(run: Run, result: Result): CommonProcessor {
+  const toolComponent: ToolComponent = findToolComponent(run, result)
+  switch (toolComponent.name) {
+    case 'CodeQL': return new CodeQLProcessor(run, result)
+    case 'Snyk Open Source': return new SnykProcessor(run, result)
+    default: return new CommonProcessor(run, result)
+  }
+}

package/src/processors/SnykProcessor.ts

@@ -0,0 +1,19 @@
+import { CommonProcessor } from './CommonProcessor'
+
+/**
+ * This class has extra logic for processing SARIF files produced by Snyk Open
+ * Source tool.
+ * @internal
+ */
+export class SnykProcessor extends CommonProcessor {
+
+  /**
+   * Rules in SARIF files produced by Snyk Open Source has additional "cvssv3_baseScore"
+   * property where CVSS score is also defined. This method tries to get level
+   * from this "cvssv3_baseScore" property and if it fails to do so, then it tries
+   * to get CVSS score in a common way.
+   */
+  public override tryFindCvssScore(): number | undefined {
+    return this.tryFindRuleProperty<number>('cvssv3_baseScore') ?? super.tryFindCvssScore()
+  }
+}

package/src/representations/CompactGroupByRepresentation.ts

@@ -0,0 +1,67 @@
+import Representation from './Representation'
+import { Finding } from '../model/Finding'
+import { findingsComparatorByKey } from '../utils/Comparators'
+import { SecurityLevel, SecuritySeverity } from '../types';
+
+const NO_VULNS_FOUND_TEXT = 'No vulnerabilities found'
+
+/**
+ * Base class of all compact representation types. By "compact" means that it
+ * groups findings by the {@link Finding} property, such as "severity" or "level".
+ * So, in fact it already prepares this in case of "severity":
+ * @example
+ * ```text
+ * Critical: 1, High: 5, Medium: 2, Low: 20, None: 1, Unknown: 120
+ * ```
+ * or this in case of "level":
+ * @example
+ * ```text
+ * Error: 6, Warning: 2, Note: 20, None: 1, Unknown: 120
+ * ```
+ * It is an abstract class, so the only question that derived classes should
+ * "answer" is how to group finding to show the compact representation.
+ * @internal
+ */
+export default abstract class CompactGroupByRepresentation extends Representation {
+
+  protected abstract groupFindings(): Map<string, Finding[]>
+
+  protected composeByProperty<K extends keyof Pick<Finding, 'level' | 'severity'>>(key: K): string {
+    const grouped: Map<string, Finding[]> = this.groupFindings()
+    if (grouped.size === 0) {
+      return NO_VULNS_FOUND_TEXT
+    }
+
+    return Array.from(grouped)
+      .map(([title, findings]: [string, Finding[]]): string => {
+        findings.sort(findingsComparatorByKey(key))
+        const summary: string =
+          findings.length === 0
+          ? NO_VULNS_FOUND_TEXT
+          : this.composeCompactReport(findings, key)
+        return `${title}\n${summary}`
+      })
+      .join('\n\n')
+  }
+
+  private composeCompactReport<K extends keyof Pick<Finding, 'level' | 'severity'>>(findings: Finding[], key: K): string {
+    return Object
+      .entries(Object.groupBy(findings, (f: Finding): PropertyKey => f[key] as PropertyKey))
+      .map(([prop, findings2]: [string, Finding[] | undefined]): string | undefined => {
+        if (findings2 == null) {
+          return undefined
+        }
+        return `${this.bold(this.extractEnumValue(key, prop))}: ${findings2.length}`
+      })
+      .filter((v: string | undefined): v is string => v != null)
+      .join(', ')
+  }
+
+  private extractEnumValue<K extends keyof Pick<Finding, 'level' | 'severity'>>(key: K, prop: string): string {
+    switch (key) {
+      case 'level': return SecurityLevel[Number(prop)]
+      case 'severity': return SecuritySeverity[Number(prop)]
+      default: throw new Error('Unknown property:', key)
+    }
+  }
+}

package/src/representations/CompactGroupByRunPerLevelRepresentation.ts

@@ -0,0 +1,14 @@
+import CompactGroupByRunRepresentation from './CompactGroupByRunRepresentation';
+
+/**
+ * Since {@link CompactGroupByRunRepresentation} 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 CompactGroupByRunPerLevelRepresentation extends CompactGroupByRunRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('level')
+  }
+}

package/src/representations/CompactGroupByRunPerSeverityRepresentation.ts

@@ -0,0 +1,14 @@
+import CompactGroupByRunRepresentation from './CompactGroupByRunRepresentation';
+
+/**
+ * Since {@link CompactGroupByRunRepresentation} 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 CompactGroupByRunPerSeverityRepresentation extends CompactGroupByRunRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('severity')
+  }
+}

package/src/representations/CompactGroupByRunRepresentation.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 run. Every run will be grouped separately, such as:
+ * @example
+ * ```text
+ * [Run 1] Grype
+ * Error: 1, Warning: 4
+ * [Run 2] Grype
+ * 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 CompactGroupByRunRepresentation extends CompactGroupByRepresentation {
+
+  public constructor(model: SarifModel) {
+    super(model, 'runId')
+  }
+
+  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.id, run.toolName)
+      if (result.get(key) == null) {
+        result.set(key, [])
+      }
+      this._model.findings
+        .filter((f: Finding): boolean => f.runId === run.id)
+        .forEach((f: Finding): number | undefined => result.get(key)?.push(f))
+    }
+    return result
+  }
+
+  private composeGroupTitle(runId: number, toolName: string): string {
+    return `${this.italic(`[Run ${runId}]`)} ${this.bold(toolName)}`
+  }
+}

package/src/representations/CompactGroupBySarifPerLevelRepresentation.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 "level".
+ * @internal
+ */
+export default class CompactGroupBySarifPerLevelRepresentation extends CompactGroupBySarifRepresentation {
+
+  public override compose(): string {
+    return this.composeByProperty('level')
+  }
+}