@fabasoad/sarif-to-slack 0.2.0 → 0.2.1

package/src/SlackMessageBuilder.ts

@@ -2,9 +2,21 @@ 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, Sarif, SlackMessage } from './types'
-import type { ReportingDescriptor, Result, Run } from 'sarif'
+import { Map as ImmutableMap } from 'immutable'
+import {
+  CalculateResultsBy,
+  FooterType,
+  GroupResultsBy,
+  SarifLog,
+  SarifToSlackOutput,
+  SlackMessage
+} from './types'
 import { LIB_VERSION } from './version'
+import {
+  DataGroupedByRun,
+  SarifModelPerSarif
+} from './model/SarifModelPerSarif';
+import { SecurityLevel, SecuritySeverity } from './model/types';
 
 /**
  * Options for the SlackMessageBuilder.
@@ -14,11 +26,10 @@ export type SlackMessageBuilderOptions = {
   username?: string
   iconUrl?: string
   color?: string
-  sarif: Sarif
+  sarif: SarifLog,
+  output?: SarifToSlackOutput,
 }
 
-type RuleData = { id?: string, index?: number }
-
 /**
  * Class for building and sending Slack messages based on SARIF logs.
  * @internal
@@ -27,22 +38,29 @@ export class SlackMessageBuilder implements SlackMessage {
   private readonly webhook: IncomingWebhook
   private readonly gitHubServerUrl: string
   private readonly color?: string
-
+  private readonly sarifModelPerSarif: SarifModelPerSarif
+  private readonly output: SarifToSlackOutput
   private header?: HeaderBlock
+
   private footer?: ContextBlock
   private actor?: string
   private runId?: string
 
-  public readonly sarif: Sarif
+  public readonly sarif: SarifLog
 
   constructor(url: string, opts: SlackMessageBuilderOptions) {
     this.webhook = new IncomingWebhook(url, {
       username: opts.username || 'SARIF results',
       icon_url: opts.iconUrl
     })
+    this.gitHubServerUrl = process.env.GITHUB_SERVER_URL || 'https://github.com'
     this.color = opts.color
     this.sarif = opts.sarif
-    this.gitHubServerUrl = process.env.GITHUB_SERVER_URL || 'https://github.com'
+    this.sarifModelPerSarif = new SarifModelPerSarif(opts.sarif)
+    this.output = opts.output || {
+      groupBy: GroupResultsBy.ToolName,
+      calculateBy: CalculateResultsBy.Level
+    }
   }
 
   withHeader(header?: string): void {
@@ -66,8 +84,8 @@ export class SlackMessageBuilder implements SlackMessage {
   withFooter(text?: string, type?: FooterType): void {
     const repoName = 'fabasoad/sarif-to-slack'
     const element: TextObject = text
-      ? { type: type || FooterType.PLAIN_TEXT, text }
-      : { type: FooterType.MARKDOWN, text: `Generated by <${this.gitHubServerUrl}/${repoName}|@${repoName}@${LIB_VERSION}>` }
+      ? { type: type || FooterType.PlainText, text }
+      : { type: FooterType.Markdown, text: `Generated by <${this.gitHubServerUrl}/${repoName}|@${repoName}@${LIB_VERSION}>` }
     this.footer = {
       type: 'context',
       elements: [element],
@@ -111,68 +129,65 @@ export class SlackMessageBuilder implements SlackMessage {
       }
       text.push(runText)
     }
-    return text.join('\n')
+    return text.join('\n\n')
   }
 
-  private composeRunSummary(toolName: string, map: Map<string, number>): string {
-    const levelsText: string[] = []
-    for (const [level, count] of map.entries()) {
-      const levelCapitalized = level.charAt(0).toUpperCase() + level.slice(1)
-      levelsText.push(`*${levelCapitalized}*: ${count}`)
+  private composeSummaryWith(
+    map: ImmutableMap<SecurityLevel | SecuritySeverity, number>,
+    resultProcessor: (result: string) => string = (result: string): string => result,
+  ): string {
+    const stats = new Array<string>()
+    for (const [key, count] of map.entries()) {
+      stats.push(`*${key}*: ${count}`)
     }
-    return `*${toolName}*\n${levelsText.join(', ')}`
+    return resultProcessor(
+      stats.length == 0 ? 'No issues found' : stats.join(', ')
+    )
   }
 
   private composeSummary(): string {
-    const data = new Map<string, Map<string, number>>()
-    for (const run of this.sarif.runs) {
-      const toolName = run.tool.driver.name
-      if (!data.has(toolName)) {
-        data.set(toolName, new Map<string, number>())
-      }
-      const results: Result[] = run.results ?? []
-      for (const result of results) {
-        const level: string = this.tryGetLevel(run, result)
-        const count: number = data.get(toolName)?.get(level) || 0
-        data.get(toolName)?.set(level, count + 1)
-      }
-    }
-    const summaries: string[] = []
-    for (const [toolName, map] of data.entries()) {
-      summaries.push(this.composeRunSummary(toolName, map))
-    }
-    return summaries.join('\n')
-  }
-
-  private tryGetLevel(run: Run, result: Result): string {
-    if (result.level) {
-      return result.level
-    }
-
-    const ruleData: RuleData = {}
-
-    if (result.rule) {
-      if (result.rule?.index) {
-        ruleData.index = result.rule.index
+    const summaries = new Array<string>()
+    switch (this.output.groupBy) {
+      case GroupResultsBy.ToolName: {
+        const dataGroupedByToolName: Map<string, ImmutableMap<SecurityLevel | SecuritySeverity, number>> =
+          this.output.calculateBy === CalculateResultsBy.Level
+            ? this.sarifModelPerSarif.groupByToolNameWithSecurityLevel()
+            : this.sarifModelPerSarif.groupByToolNameWithSecuritySeverity()
+        for (const [toolName, map] of dataGroupedByToolName.entries()) {
+          summaries.push(this.composeSummaryWith(
+            map,
+            (result: string): string => `*${toolName}*\n${result}`
+          ))
+        }
+        break
       }
-      if (result.rule?.id) {
-        ruleData.id = result.rule.id
+      case GroupResultsBy.Run: {
+        const dataGroupedByRun: Array<DataGroupedByRun<SecurityLevel | SecuritySeverity>> =
+          this.output.calculateBy === CalculateResultsBy.Level
+            ? this.sarifModelPerSarif.groupByRunWithSecurityLevel()
+            : this.sarifModelPerSarif.groupByRunWithSecuritySeverity()
+        for (let i = 0; i < dataGroupedByRun.length; i++) {
+          const { data, toolName } = dataGroupedByRun[i]
+          summaries.push(this.composeSummaryWith(
+            data,
+            (result: string): string => `_[Run ${i + 1}]_: *${toolName}*\n${result}`
+          ))
+        }
+        break
       }
-    }
-
-    if (!ruleData.index && result.ruleIndex) {
-      ruleData.index = result.ruleIndex
-    }
-
-    if (ruleData.index
-      && run.tool.driver?.rules
-      && ruleData.index < run.tool.driver.rules.length) {
-      const rule: ReportingDescriptor = run.tool.driver.rules[ruleData.index]
-      if (rule.properties && 'problem.severity' in rule.properties) {
-        return rule.properties['problem.severity'] as string
+      default: {
+        const dataTotal: ImmutableMap<SecurityLevel | SecuritySeverity, number> =
+          this.output.calculateBy === CalculateResultsBy.Level
+            ? this.sarifModelPerSarif.groupByTotalWithSecurityLevel()
+            : this.sarifModelPerSarif.groupByTotalWithSecuritySeverity()
+        const toolNames: Set<string> = this.sarifModelPerSarif.listToolNames()
+        summaries.push(this.composeSummaryWith(
+          dataTotal,
+          (result: string): string => `*${Array.from(toolNames).join('*, *')}*\n${result}`
+        ))
+        break
       }
     }
-
-    return 'unknown'
+    return summaries.join('\n\n')
   }
 }

package/src/index.ts

@@ -14,7 +14,11 @@
  * const service = await SarifToSlackService.create({
  *   webhookUrl: 'https://hooks.slack.com/services/your/webhook/url',
  *   sarifPath: 'path/to/your/sarif/file.sarif',
- *   logLevel: 'info',
+ *   log: {
+ *     level: 'info',
+ *     template: '[{{logLevelName}}] [{{name}}] {{dateIsoStr}} ',
+ *     colored: false,
+ *   },
  *   username: 'SARIF Bot',
  *   iconUrl: 'https://example.com/icon.png',
  *   color: '#36a64f',
@@ -44,12 +48,16 @@
  */
 export { SarifToSlackService } from './SarifToSlackService'
 export {
+  CalculateResultsBy,
   FooterOptions,
   FooterType,
+  GroupResultsBy,
   IncludeAwareOptions,
   IncludeAwareWithValueOptions,
   LogLevel,
-  Sarif,
+  LogOptions,
+  SarifLog,
+  SarifToSlackOutput,
   SarifToSlackServiceOptions,
   SlackMessage,
 } from './types'

package/src/model/SarifModelPerRun.ts

@@ -0,0 +1,114 @@
+import type { Result, Run } from 'sarif';
+import { tryGetRulePropertyByResult } from '../utils/SarifUtils'
+import { SecurityLevel, SecuritySeverity } from './types'
+import Logger from '../Logger'
+import { Map as ImmutableMap } from 'immutable'
+import {
+  sortSecurityLevelMap,
+  sortSecuritySeverityMap
+} from '../utils/SortUtils';
+
+export class SarifModelPerRun {
+  public readonly toolName: string
+
+  private readonly _securitySeverityMap: ImmutableMap<SecuritySeverity, number>
+  private readonly _securityLevelMap: ImmutableMap<SecurityLevel, number>
+
+  constructor(run: Run) {
+    this.toolName = run.tool.driver.name
+
+    this._securitySeverityMap = ImmutableMap<SecuritySeverity, number>().asMutable()
+    this._securityLevelMap = ImmutableMap<SecurityLevel, number>().asMutable()
+
+    this.buildSecuritySeverityMap(run)
+    this.buildSecurityLevelMap(run)
+  }
+
+  private identifySecuritySeverity(score?: number): SecuritySeverity {
+    if (score === undefined) {
+      return SecuritySeverity.Unknown
+    }
+
+    if (score >= 9 && score <= 10) {
+      return SecuritySeverity.Critical
+    }
+
+    if (score >= 7) {
+      return SecuritySeverity.High
+    }
+
+    if (score >= 4) {
+      return SecuritySeverity.Medium
+    }
+
+    if (score >= 0.1) {
+      return SecuritySeverity.Low
+    }
+
+    if (score == 0) {
+      return SecuritySeverity.None
+    }
+
+    Logger.warn(`Unsupported "${score}" security severity. Saving as "Unknown".`)
+    return SecuritySeverity.Unknown
+  }
+
+  private identifySecurityLevel(level?: string): SecurityLevel {
+    if (level === undefined) {
+      return SecurityLevel.Unknown
+    }
+
+    if (level.toLowerCase() === 'error') {
+      return SecurityLevel.Error
+    }
+
+    if (level.toLowerCase() === 'warning') {
+      return SecurityLevel.Warning
+    }
+
+    if (level.toLowerCase() === 'note') {
+      return SecurityLevel.Note
+    }
+
+    Logger.warn(`Unsupported ${level} security level. Saving as "Unknown".`)
+    return SecurityLevel.Unknown
+  }
+
+  private buildSecuritySeverityMap(run: Run): void {
+    const results: Result[] = run.results ?? []
+    for (const result of results) {
+      const severity: SecuritySeverity = this.identifySecuritySeverity(
+        tryGetRulePropertyByResult(run, result, 'security-severity')
+      )
+      const count: number = this._securitySeverityMap.get(severity) || 0
+      this._securitySeverityMap.set(severity, count + 1)
+    }
+  }
+
+  private tryGetSecurityLevel(run: Run, result: Result): string | undefined {
+    if (result.level) {
+      return result.level
+    }
+
+    return tryGetRulePropertyByResult(run, result, 'problem.severity')
+  }
+
+  private buildSecurityLevelMap(run: Run): void {
+    const results: Result[] = run.results ?? []
+    for (const result of results) {
+      const level: SecurityLevel = this.identifySecurityLevel(
+        this.tryGetSecurityLevel(run, result)
+      )
+      const count: number = this._securityLevelMap.get(level) || 0
+      this._securityLevelMap.set(level, count + 1)
+    }
+  }
+
+  public get securitySeverityMap(): ImmutableMap<SecuritySeverity, number> {
+    return sortSecuritySeverityMap(this._securitySeverityMap)
+  }
+
+  public get securityLevelMap(): ImmutableMap<SecurityLevel, number> {
+    return sortSecurityLevelMap(this._securityLevelMap)
+  }
+}

package/src/model/SarifModelPerSarif.ts

@@ -0,0 +1,116 @@
+import type { SarifLog } from '../types'
+import { Map as ImmutableMap } from 'immutable'
+import { SarifModelPerRun } from './SarifModelPerRun'
+import { SecurityLevel, SecuritySeverity } from './types'
+import {
+  sortSecurityLevelMap,
+  sortSecuritySeverityMap
+} from '../utils/SortUtils';
+
+export type DataGroupedByRun<T> = {
+  toolName: string,
+  data: ImmutableMap<T, number>
+}
+
+export class SarifModelPerSarif {
+  private readonly sarifModelPerRunList: Array<SarifModelPerRun>;
+
+  constructor(sarif: SarifLog) {
+    this.sarifModelPerRunList = new Array<SarifModelPerRun>()
+    this.buildRunsList(sarif)
+  }
+
+  private buildRunsList(sarif: SarifLog): void {
+    for (const run of sarif.runs) {
+      this.sarifModelPerRunList.push(new SarifModelPerRun(run))
+    }
+  }
+
+  public groupByToolNameWithSecurityLevel(): Map<string, ImmutableMap<SecurityLevel, number>> {
+    const result = new Map<string, ImmutableMap<SecurityLevel, number>>()
+    for (const sarifModelPerRun of this.sarifModelPerRunList) {
+      if (!result.has(sarifModelPerRun.toolName)) {
+        result.set(sarifModelPerRun.toolName, ImmutableMap<SecurityLevel, number>().asMutable())
+      }
+      for (const [k, v] of sarifModelPerRun.securityLevelMap.entries()) {
+        const count: number = result.get(sarifModelPerRun.toolName)?.get(k) || 0
+        result.get(sarifModelPerRun.toolName)?.set(k, count + v)
+      }
+    }
+    // Sort
+    for (const [k, v] of result) {
+      result.set(k, sortSecurityLevelMap(v))
+    }
+    return result
+  }
+
+  public groupByRunWithSecurityLevel(): DataGroupedByRun<SecurityLevel>[] {
+    const result = new Array<DataGroupedByRun<SecurityLevel>>()
+    for (const sarifModelPerRun of this.sarifModelPerRunList) {
+      result.push({
+        toolName: sarifModelPerRun.toolName,
+        data: sarifModelPerRun.securityLevelMap,
+      })
+    }
+    return result
+  }
+
+  public groupByTotalWithSecurityLevel(): ImmutableMap<SecurityLevel, number> {
+    const result = ImmutableMap<SecurityLevel, number>().asMutable()
+    for (const sarifModelPerRun of this.sarifModelPerRunList) {
+      for (const [k, v] of sarifModelPerRun.securityLevelMap.entries()) {
+        const count: number = result.get(k) || 0
+        result.set(k, count + v)
+      }
+    }
+    return sortSecurityLevelMap(result)
+  }
+
+  public groupByToolNameWithSecuritySeverity(): Map<string, ImmutableMap<SecuritySeverity, number>> {
+    const result = new Map<string, ImmutableMap<SecuritySeverity, number>>()
+    for (const sarifModelPerRun of this.sarifModelPerRunList) {
+      if (!result.has(sarifModelPerRun.toolName)) {
+        result.set(sarifModelPerRun.toolName, ImmutableMap<SecuritySeverity, number>().asMutable())
+      }
+      for (const [k, v] of sarifModelPerRun.securitySeverityMap.entries()) {
+        const count: number = result.get(sarifModelPerRun.toolName)?.get(k) || 0
+        result.get(sarifModelPerRun.toolName)?.set(k, count + v)
+      }
+    }
+    // Sort
+    for (const [k, v] of result.entries()) {
+      result.set(k, sortSecuritySeverityMap(v))
+    }
+    return result
+  }
+
+  public groupByRunWithSecuritySeverity(): DataGroupedByRun<SecuritySeverity>[] {
+    const result = new Array<DataGroupedByRun<SecuritySeverity>>()
+    for (const sarifModelPerRun of this.sarifModelPerRunList) {
+      result.push({
+        toolName: sarifModelPerRun.toolName,
+        data: sarifModelPerRun.securitySeverityMap,
+      })
+    }
+    return result
+  }
+
+  public groupByTotalWithSecuritySeverity(): ImmutableMap<SecuritySeverity, number> {
+    const result = ImmutableMap<SecuritySeverity, number>().asMutable()
+    for (const sarifModelPerRun of this.sarifModelPerRunList) {
+      for (const [k, v] of sarifModelPerRun.securitySeverityMap.entries()) {
+        const count: number = result.get(k) || 0
+        result.set(k, count + v)
+      }
+    }
+    return sortSecuritySeverityMap(result)
+  }
+
+  public listToolNames(): Set<string> {
+    const toolNames = new Set<string>()
+    for (const sarifModelPerRun of this.sarifModelPerRunList) {
+      toolNames.add(sarifModelPerRun.toolName)
+    }
+    return toolNames
+  }
+}

package/src/model/types.ts

@@ -0,0 +1,31 @@
+export enum SecuritySeverity {
+  Unknown = 'Unknown',
+  None = 'None',
+  Low = 'Low',
+  Medium = 'Medium',
+  High = 'High',
+  Critical = 'Critical'
+}
+
+export const SecuritySeverityOrder: SecuritySeverity[] = [
+  SecuritySeverity.Critical,
+  SecuritySeverity.High,
+  SecuritySeverity.Medium,
+  SecuritySeverity.Low,
+  SecuritySeverity.None,
+  SecuritySeverity.Unknown
+]
+
+export enum SecurityLevel {
+  Unknown = 'Unknown',
+  Note = 'Note',
+  Warning = 'Warning',
+  Error = 'Error'
+}
+
+export const SecurityLevelOrder: SecurityLevel[] = [
+  SecurityLevel.Error,
+  SecurityLevel.Warning,
+  SecurityLevel.Note,
+  SecurityLevel.Unknown
+]

package/src/types.ts

@@ -4,7 +4,7 @@ import type { Log } from 'sarif'
  * Type representing a SARIF log.
  * @public
  */
-export type Sarif = Log
+export type SarifLog = Log
 
 /**
  * Interface for a Slack message that can be sent.
@@ -19,7 +19,7 @@ export interface SlackMessage {
   /**
    * The SARIF log associated with this Slack message.
    */
-  sarif: Sarif
+  sarif: SarifLog
 }
 
 /**
@@ -28,7 +28,8 @@ export interface SlackMessage {
  */
 export enum LogLevel {
   /**
-   * Represents the most verbose logging level, typically used for detailed debugging information.
+   * Represents the most verbose logging level, typically used for detailed
+   * debugging information.
    */
   Silly = 0,
   /**
@@ -36,23 +37,28 @@ export enum LogLevel {
    */
   Trace = 1,
   /**
-   * Represents a logging level for debugging information that is less verbose than silly.
+   * Represents a logging level for debugging information that is less verbose
+   * than silly.
    */
   Debug = 2,
   /**
-   * Represents a logging level for general informational messages that highlight the progress of the application.
+   * Represents a logging level for general informational messages that highlight
+   * the progress of the application.
    */
   Info = 3,
   /**
-   * Represents a logging level for potentially harmful situations that require attention.
+   * Represents a logging level for potentially harmful situations that require
+   * attention.
    */
   Warning = 4,
   /**
-   * Represents a logging level for error conditions that do not require immediate action but should be noted.
+   * Represents a logging level for error conditions that do not require immediate
+   * action but should be noted.
    */
   Error = 5,
   /**
-   * Represents a logging level for critical errors that require immediate attention and may cause the application to terminate.
+   * Represents a logging level for critical errors that require immediate attention
+   * and may cause the application to terminate.
    */
   Fatal = 6
 }
@@ -80,8 +86,15 @@ export type IncludeAwareWithValueOptions = IncludeAwareOptions & {
  * @public
  */
 export enum FooterType {
-  PLAIN_TEXT = 'plain_text',
-  MARKDOWN = 'mrkdwn'
+  /**
+   * Represents a plain text footer. Text is not formatted and appears as-is.
+   */
+  PlainText = 'plain_text',
+  /**
+   * Represents a footer with Markdown formatting. Text can include formatting
+   * such as bold, italics, and links.
+   */
+  Markdown = 'mrkdwn'
 }
 
 /**
@@ -93,6 +106,72 @@ export type FooterOptions = IncludeAwareWithValueOptions & {
   type?: FooterType
 }
 
+/**
+ * Enum representing how to group results.
+ * @public
+ */
+export enum GroupResultsBy {
+  /**
+   * Groups results by the tool name. Particularly, groups by the runs[].tool.driver.name
+   * property from the SARIF file(s).
+   */
+  ToolName = 0,
+  /**
+   * Groups results by the run. It provides the result from each run individually.
+   */
+  Run = 1,
+  /**
+   * Does not group results. It provides the result from all the runs from all
+   * the provided SARIF files.
+   */
+  Total = 2,
+}
+
+/**
+ * Enum representing how to calculate results.
+ * @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,
+  /**
+   * 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.
+   */
+  Severity = 1,
+}
+
+/**
+ * Options for how to output the results in the Slack message.
+ * @public
+ */
+export type SarifToSlackOutput = {
+  groupBy: GroupResultsBy,
+  calculateBy: CalculateResultsBy,
+}
+
+/**
+ * Options for logging.
+ * @public
+ */
+export type LogOptions = {
+  level?: LogLevel,
+  /**
+   * More details here: https://github.com/fullstack-build/tslog?tab=readme-ov-file#pretty-templates-and-styles-color-settings
+   */
+  template?: string,
+  colored?: boolean,
+}
+
 /**
  * Options for the SarifToSlackService.
  * @public
@@ -104,9 +183,10 @@ export type SarifToSlackServiceOptions = {
   username?: string,
   iconUrl?: string,
   color?: string,
-  logLevel?: LogLevel | string,
+  log?: LogOptions,
   header?: IncludeAwareWithValueOptions,
   footer?: FooterOptions,
   actor?: IncludeAwareWithValueOptions,
   run?: IncludeAwareOptions,
+  output?: SarifToSlackOutput,
 }