@fabasoad/sarif-to-slack 0.2.5 → 1.1.0

package/src/SarifToSlackClient.ts

@@ -0,0 +1,202 @@
+import { promises as fs } from 'fs'
+import { Log } from 'sarif'
+import Logger from './Logger'
+import { SlackMessageBuilder } from './SlackMessageBuilder'
+import {
+  LogOptions,
+  RunData,
+  SarifModel,
+  SarifOptions,
+  SarifToSlackClientOptions,
+  SecurityLevel,
+  SecuritySeverity,
+  SendIf,
+  SlackMessage
+} from './types'
+import System from './System'
+import { extractListOfFiles } from './utils/FileUtils'
+import { createRepresentation } from './representations/RepresentationFactory'
+import { createFinding } from './model/Finding'
+import { findToolComponent, findToolComponentDriver } from './utils/SarifUtils'
+import { identifyColor } from './model/Color'
+import FindingsArray from './model/FindingsArray'
+
+/**
+ * Service to convert SARIF files to Slack messages and send them.
+ * @public
+ */
+export class SarifToSlackClient {
+  private _message?: SlackMessage
+  private _sarifModel?: SarifModel
+
+  private _sendIf: SendIf = SendIf.Always
+
+  private constructor(log?: LogOptions) {
+    Logger.initialize(log)
+    System.initialize()
+  }
+
+  private static *createRunIdGenerator(): Generator<number> {
+    let runId: number = 1
+    while (true) {
+      yield runId++
+    }
+  }
+
+  public static async create(opts: SarifToSlackClientOptions): Promise<SarifToSlackClient> {
+    const instance = new SarifToSlackClient(opts.log)
+    Logger.trace('opts', opts)
+    instance._sendIf = opts.sendIf ?? instance._sendIf
+    instance._sarifModel = await SarifToSlackClient.buildModel(opts.sarif)
+    Logger.trace('instance._sarifModel', instance._sarifModel)
+    instance._message = await SarifToSlackClient.initialize(instance._sarifModel, opts)
+    Logger.trace('instance._message', instance._message)
+    return instance;
+  }
+
+  private static async buildModel(sarifOpts: SarifOptions): Promise<SarifModel> {
+    const sarifFiles: string[] = extractListOfFiles(sarifOpts)
+    if (sarifFiles.length === 0) {
+      throw new Error(`No SARIF files found at the provided path: ${sarifOpts.path}`)
+    }
+
+    const model: SarifModel = { sarifFiles, runs: [], findings: new FindingsArray() }
+    const runIdGenerator: Generator<number> = SarifToSlackClient.createRunIdGenerator()
+    for (const sarifPath of sarifFiles) {
+      const sarifJson: string = await fs.readFile(sarifPath, 'utf8')
+      const sarifLog: Log = JSON.parse(sarifJson) as Log
+
+      for (const run of sarifLog.runs) {
+        const runId: IteratorResult<number> = runIdGenerator.next()
+        let runMetadata: RunData | undefined = undefined
+        for (const result of run.results ?? []) {
+          runMetadata = {
+            id: runId.value,
+            run,
+            toolName: findToolComponent(run, result).name
+          }
+          model.findings.push(createFinding({ sarifPath, result, runMetadata }))
+        }
+        runMetadata ??= {
+          id: runId.value, run, toolName: findToolComponentDriver(run).name
+        }
+        model.runs.push(runMetadata)
+      }
+    }
+    return model
+  }
+
+  /**
+   * The main function to initialize a list of {@link SlackMessage} objects based
+   * on the given SARIF file(s).
+   * @param sarifModel An instance of {@link SarifModel} object.
+   * @param opts An instance of {@link SarifToSlackClientOptions} object.
+   * @returns A map where key is the SARIF file and value is an instance of
+   * {@link SlackMessage} object
+   * @private
+   */
+  private static async initialize(
+    sarifModel: SarifModel,
+    opts: Omit<SarifToSlackClientOptions, 'sarif' | 'log' | 'sendIf'>
+  ): Promise<SlackMessage> {
+    const message: SlackMessage = new SlackMessageBuilder(opts.webhookUrl, {
+      username: opts.username,
+      iconUrl: opts.iconUrl,
+      color: identifyColor(sarifModel.findings, opts.color),
+      representation: createRepresentation(sarifModel, opts.representation),
+    })
+    if (opts.header?.include) {
+      message.withHeader(opts.header?.value)
+    }
+    if (opts.footer?.include) {
+      message.withFooter(opts.footer?.value, opts.footer?.type)
+    }
+    if (opts.actor?.include) {
+      message.withActor(opts.actor?.value)
+    }
+    if (opts.run?.include) {
+      message.withRun()
+    }
+    return message
+  }
+
+  /**
+   * Sends a Slack message.
+   * @returns A promise that resolves when the message has been sent.
+   * @throws Error if a Slack message was not prepared for the given SARIF path.
+   * @public
+   */
+  public async send(): Promise<void> {
+    if (this._sarifModel == null) {
+      throw new Error('Could not parse SARIF file(s).')
+    }
+    if (this.shouldSendMessage) {
+      if (this._message == null) {
+        throw new Error('Slack message was not prepared.')
+      }
+      const text: string = await this._message.send()
+      Logger.info('Message sent. Status:', text)
+    } else {
+      Logger.info('Message was not sent based on the sendIf parameter:', SendIf[this._sendIf])
+    }
+  }
+
+  private get shouldSendMessage(): boolean {
+    if (this._sendIf == null) {
+      return true
+    }
+
+    switch (this._sendIf) {
+      case SendIf.SeverityCritical:
+        return this._sarifModel?.findings.findByProperty('severity', SecuritySeverity.Critical) != null
+      case SendIf.SeverityHigh:
+        return this._sarifModel?.findings.findByProperty('severity', SecuritySeverity.High) != null
+      case SendIf.SeverityHighOrHigher:
+        return !!this._sarifModel?.findings.hasSeverityOrHigher(SecuritySeverity.High)
+      case SendIf.SeverityMedium:
+        return this._sarifModel?.findings.findByProperty('severity', SecuritySeverity.Medium) != null
+      case SendIf.SeverityMediumOrHigher:
+        return !!this._sarifModel?.findings.hasSeverityOrHigher(SecuritySeverity.Medium)
+      case SendIf.SeverityLow:
+        return this._sarifModel?.findings.findByProperty('severity', SecuritySeverity.Low) != null
+      case SendIf.SeverityLowOrHigher:
+        return !!this._sarifModel?.findings.hasSeverityOrHigher(SecuritySeverity.Low)
+      case SendIf.SeverityNone:
+        return this._sarifModel?.findings.findByProperty('severity', SecuritySeverity.None) != null
+      case SendIf.SeverityNoneOrHigher:
+        return !!this._sarifModel?.findings.hasSeverityOrHigher(SecuritySeverity.None)
+      case SendIf.SeverityUnknown:
+        return this._sarifModel?.findings.findByProperty('severity', SecuritySeverity.Unknown) != null
+      case SendIf.SeverityUnknownOrHigher:
+        return !!this._sarifModel?.findings.hasSeverityOrHigher(SecuritySeverity.Unknown)
+      case SendIf.LevelError:
+        return this._sarifModel?.findings.findByProperty('level', SecurityLevel.Error) != null
+      case SendIf.LevelWarning:
+        return this._sarifModel?.findings.findByProperty('level', SecurityLevel.Warning) != null
+      case SendIf.LevelWarningOrHigher:
+        return !!this._sarifModel?.findings.hasLevelOrHigher(SecurityLevel.Warning)
+      case SendIf.LevelNote:
+        return this._sarifModel?.findings.findByProperty('level', SecurityLevel.Note) != null
+      case SendIf.LevelNoteOrHigher:
+        return !!this._sarifModel?.findings.hasLevelOrHigher(SecurityLevel.Note)
+      case SendIf.LevelNone:
+        return this._sarifModel?.findings.findByProperty('level', SecurityLevel.None) != null
+      case SendIf.LevelNoneOrHigher:
+        return !!this._sarifModel?.findings.hasLevelOrHigher(SecurityLevel.None)
+      case SendIf.LevelUnknown:
+        return this._sarifModel?.findings.findByProperty('level', SecurityLevel.Unknown) != null
+      case SendIf.LevelUnknownOrHigher:
+        return !!this._sarifModel?.findings.hasLevelOrHigher(SecurityLevel.Unknown)
+      case SendIf.Always:
+        return true
+      case SendIf.Some:
+        return (this._sarifModel?.findings.length ?? 0) > 0
+      case SendIf.Empty:
+        return (this._sarifModel?.findings.length ?? 0) === 0
+      case SendIf.Never:
+        return false
+      default:
+        throw new Error(`Unknown sendIf parameter: ${this._sendIf}`)
+    }
+  }
+}

package/src/SlackMessageBuilder.ts

@@ -2,21 +2,9 @@ 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 { Map as ImmutableMap } from 'immutable'
-import {
-  CalculateResultsBy,
-  FooterType,
-  GroupResultsBy,
-  SarifLog,
-  SarifToSlackOutput,
-  SlackMessage
-} from './types'
-import { LIB_VERSION } from './metadata'
-import {
-  DataGroupedByRun,
-  SarifModelPerSarif
-} from './model/SarifModelPerSarif';
-import { SecurityLevel, SecuritySeverity } from './model/types';
+import { FooterType, SlackMessage } from './types'
+import { version } from './metadata.json'
+import Representation from './representations/Representation'
 
 /**
  * Options for the SlackMessageBuilder.
@@ -26,8 +14,7 @@ export type SlackMessageBuilderOptions = {
   username?: string
   iconUrl?: string
   color?: string
-  sarif: SarifLog,
-  output?: SarifToSlackOutput,
+  representation: Representation,
 }
 
 /**
@@ -35,36 +22,28 @@ export type SlackMessageBuilderOptions = {
  * @internal
  */
 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 readonly _webhook: IncomingWebhook
+  private readonly _gitHubServerUrl: string
+  private readonly _color?: string
+  private readonly _representation: Representation
 
-  private footer?: ContextBlock
-  private actor?: string
-  private runId?: string
-
-  public readonly sarif: SarifLog
+  private _header?: HeaderBlock
+  private _footer?: ContextBlock
+  private _actor?: string
+  private _runId?: string
 
   constructor(url: string, opts: SlackMessageBuilderOptions) {
-    this.webhook = new IncomingWebhook(url, {
+    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.sarifModelPerSarif = new SarifModelPerSarif(opts.sarif)
-    this.output = opts.output || {
-      groupBy: GroupResultsBy.ToolName,
-      calculateBy: CalculateResultsBy.Level
-    }
+    this._gitHubServerUrl = process.env.GITHUB_SERVER_URL || 'https://github.com'
+    this._color = opts.color
+    this._representation = opts.representation
   }
 
   withHeader(header?: string): void {
-    this.header = {
+    this._header = {
       type: 'header',
       text: {
         type: 'plain_text',
@@ -74,19 +53,19 @@ export class SlackMessageBuilder implements SlackMessage {
   }
 
   withActor(actor?: string): void {
-    this.actor = actor || process.env.GITHUB_ACTOR
+    this._actor = actor || process.env.GITHUB_ACTOR
   }
 
   withRun(): void {
-    this.runId = process.env.GITHUB_RUN_ID
+    this._runId = process.env.GITHUB_RUN_ID
   }
 
   withFooter(text?: string, type?: FooterType): void {
     const repoName = 'fabasoad/sarif-to-slack'
     const element: TextObject = text
       ? { type: type || FooterType.PlainText, text }
-      : { type: FooterType.Markdown, text: `Generated by <${this.gitHubServerUrl}/${repoName}|@${repoName}@${LIB_VERSION}>` }
-    this.footer = {
+      : { type: FooterType.Markdown, text: `Generated by <${this._gitHubServerUrl}/${repoName}|@${repoName}@${version}>` }
+    this._footer = {
       type: 'context',
       elements: [element],
     }
@@ -94,100 +73,41 @@ export class SlackMessageBuilder implements SlackMessage {
 
   async send(): Promise<string> {
     const blocks: AnyBlock[] = []
-    if (this.header) {
-      blocks.push(this.header)
+    if (this._header) {
+      blocks.push(this._header)
     }
     blocks.push({
       type: 'section',
       text: {
         type: 'mrkdwn',
-        text: this.buildText()
+        text: this.buildText(),
       }
     })
-    if (this.footer) {
-      blocks.push(this.footer)
+    if (this._footer) {
+      blocks.push(this._footer)
     }
-    const { text } = await this.webhook.send({
-      attachments: [{ color: this.color, blocks }]
+    const { text } = await this._webhook.send({
+      attachments: [{ color: this._color, blocks }]
     })
     return text
   }
 
   private buildText(): string {
     const text: string[] = []
-    if (this.actor) {
-      const actorUrl = `${this.gitHubServerUrl}/${this.actor}`
-      text.push(`_Triggered by <${actorUrl}|${this.actor}>_`)
+    if (this._actor) {
+      const actorUrl = `${this._gitHubServerUrl}/${this._actor}`
+      text.push(`_Triggered by <${actorUrl}|${this._actor}>_`)
     }
-    text.push(this.composeSummary())
-    if (this.runId) {
+    text.push(this._representation.compose())
+    if (this._runId) {
       let runText: string = 'Job '
       if (process.env.GITHUB_REPOSITORY) {
-        runText += `<${this.gitHubServerUrl}/${process.env.GITHUB_REPOSITORY}/actions/runs/${this.runId}|#${this.runId}>`
+        runText += `<${this._gitHubServerUrl}/${process.env.GITHUB_REPOSITORY}/actions/runs/${this._runId}|#${this._runId}>`
       } else {
-        runText += `#${this.runId}`
+        runText += `#${this._runId}`
       }
       text.push(runText)
     }
     return text.join('\n\n')
   }
-
-  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 resultProcessor(
-      stats.length == 0 ? 'No issues found' : stats.join(', ')
-    )
-  }
-
-  private composeSummary(): string {
-    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
-      }
-      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
-      }
-      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 summaries.join('\n\n')
-  }
 }

package/src/System.ts

@@ -1,9 +1,16 @@
-import { LIB_VERSION } from './metadata'
+import { version, sha, buildAt } from './metadata.json'
 import Logger from './Logger'
 
+/**
+ * This class prints metadata information into the logs, such as library version,
+ * SHA and build time.
+ * @internal
+ */
 export default class System {
 
   public static initialize(): void {
-    Logger.info(`Version: ${LIB_VERSION}`)
+    Logger.info(`@fabasoad/sarif-to-slack version: ${version}`)
+    Logger.info(`@fabasoad/sarif-to-slack sha: ${sha}`)
+    Logger.info(`@fabasoad/sarif-to-slack built at: ${buildAt}`)
   }
 }

package/src/index.ts

@@ -4,24 +4,45 @@
  * Sarif to Slack message converter library.
  *
  * @remarks
- * This library provides a service to send a Slack messages based on the provided
+ * This library provides a client to send a Slack messages based on the provided
  * SARIF (Static Analysis Results Interchange Format) files.
  *
  * @example
  * ```typescript
- * import { SarifToSlackService, FooterType } from '@fabasoad/sarif-to-slack';
+ * import {
+ *   Color,
+ *   FooterType,
+ *   LogLevel,
+ *   RepresentationType,
+ *   SarifToSlackClient,
+ *   SendIf
+ * } from '@fabasoad/sarif-to-slack';
  *
- * const service = await SarifToSlackService.create({
+ * const client: SarifToSlackClient = await SarifToSlackClient.create({
  *   webhookUrl: 'https://hooks.slack.com/services/your/webhook/url',
- *   sarifPath: 'path/to/your/sarif/file.sarif',
+ *   username: 'SARIF to Slack Bot',
+ *   iconUrl: 'https://example.com/icon.png',
+ *   color: {
+ *     bySeverity: {
+ *       critical: new Color('#ff0000'),
+ *       high: new Color('#ff4500'),
+ *       medium: new Color('#ffa500'),
+ *       low: new Color('#ffff00'),
+ *       none: new Color('#808080'),
+ *       unknown: new Color('#800080'),
+ *       empty: new Color('#d3d3d3'),
+ *     },
+ *   },
+ *   sarif: {
+ *     path: 'path/to/your/sarif-files',
+ *     recursive: true,
+ *     extension: 'sarif',
+ *   },
  *   log: {
  *     level: LogLevel.Info,
  *     template: '[{{logLevelName}}] [{{name}}] {{dateIsoStr}} ',
  *     colored: false,
  *   },
- *   username: 'SARIF Bot',
- *   iconUrl: 'https://example.com/icon.png',
- *   color: '#36a64f',
  *   header: {
  *     include: true,
  *     value: 'SARIF Analysis Results'
@@ -38,28 +59,34 @@
  *   run: {
  *     include: true
  *   },
+ *   representation: RepresentationType.CompactGroupByToolNamePerSeverity,
+ *   sendIf: SendIf.MediumOrHigher,
  * });
- * await service.sendAll();
+ * await client.send();
  * ```
  *
- * @see {@link SarifToSlackService}
+ * @see {@link SarifToSlackClient}
  *
  * @packageDocumentation
  */
-export { SarifToSlackService } from './SarifToSlackService'
 export {
-  CalculateResultsBy,
-  FooterType,
-  GroupResultsBy,
-  LogLevel,
-  SlackMessage
-} from './types'
-export type {
+  Color,
+  ColorOptions,
+  ColorGroupByLevel,
+  ColorGroupBySeverity
+} from './model/Color'
+export { SarifToSlackClient } from './SarifToSlackClient'
+export {
   FooterOptions,
+  FooterType,
   IncludeAwareOptions,
   IncludeAwareWithValueOptions,
+  LogLevel,
   LogOptions,
-  SarifLog,
-  SarifToSlackOutput,
-  SarifToSlackServiceOptions
+  RepresentationType,
+  SarifFileExtension,
+  SarifOptions,
+  SarifToSlackClientOptions,
+  SendIf,
+  SlackMessage,
 } from './types'