@eurekadevsecops/radar 1.0.0

package/scanners/opengrep/run.sh

@@ -0,0 +1,7 @@
+# Parameters:
+# $1 - Path to the source code folder that should be scanned
+# $2 - Path to the assets folder
+# $3 - Path to the output folder where scan results should be stored
+
+set -e
+docker run --rm -t -v $1:/app -v $2:/input -v $3:/home/output radar/opengrep:latest /app 2>&1

package/scanners/scanners.toml

@@ -0,0 +1,20 @@
+[[scanners]]
+name = "depscan"
+title = "OWASP dep-scan"
+description = "Next-generation security and risk audit tool."
+categories = [ "SCA" ]
+cmd = "${assets}/run.sh ${target} ${assets} ${output}"
+
+[[scanners]]
+name = "opengrep"
+title = "Opengrep"
+description = "Ultra-fast static analysis tool."
+categories = [ "SAST" ]
+cmd = "${assets}/run.sh ${target} ${assets} ${output}"
+
+[[scanners]]
+name = "gitleaks"
+title = "Gitleaks"
+description = "Detect secrets like passwords, API keys, and tokens in source code."
+categories = [ "SAST" ]
+cmd = "${assets}/run.sh ${target} ${assets} ${output}"

package/src/commands/index.js

@@ -0,0 +1,5 @@
+module.exports = {
+  help: 'display help',
+  scan: require('./scan'),
+  scanners: require('./scanners')
+}

package/src/commands/scan.js

@@ -0,0 +1,237 @@
+const util = require('node:util')
+const exec = util.promisify(require('node:child_process').exec)
+const fs = require('node:fs')
+const path = require('node:path')
+const { performance } = require('node:perf_hooks')
+const os = require('node:os')
+const { default: Spinner } = require('tiny-spinner')
+const humanize = require('../util/humanize')
+const sariftools = require('../util/sarif')
+module.exports = {
+  summary: 'scan for vulnerabilities',
+  args: {
+    TARGET: {
+      description: 'target to scan',
+      optional: true,
+      validate: TARGET => {
+        if (!fs.existsSync(path.normalize(TARGET))) throw new Error(`path doesn't exist: ${TARGET}`)
+      }
+    }
+  },
+  options: [
+    { name: 'CATEGORIES', short: 'c', long: 'categories', type: 'string', description: 'list of scanner categories' },
+    { name: 'ERRORS', short: 'e', long: 'errors', type: 'string', description: 'severities to treat as errors' },
+    { name: 'FORMAT', short: 'f', long: 'format', type: 'string', description: 'severity format' },
+    { name: 'OUTPUT', short: 'o', long: 'output', type: 'string', description: 'output SARIF file' },
+    { name: 'QUIET', short: 'q', long: 'quiet', type: 'boolean', description: 'suppress stdout logging' },
+    { name: 'SCANNERS', short: 's', long: 'scanners', type: 'string', description: 'list of scanners to use' }
+  ],
+  description: `
+    Scans a target for vulnerabilities. Defaults to displaying findings on stdout.
+    If TARGET argument is ommitted, it defaults to current working directory.
+
+    When quiet mode is selected with the QUIET command-line option, most stdout
+    logs are ommitted except for errors that occur with the scanning process. To
+    suppress SARIF output on stdout, use the OUTPUT option to save findings into
+    a file on disk.
+
+    By default, all scanners are used. If you want to limit your scan to a subset
+    of available scanners, use the SCANNERS option. You can provide a specific
+    list of scanners, comma-separated, that will be used to run the scan. Scanner
+    names passed into the SCANNERS option should match the scanner names returned
+    by the "scanners" command.
+
+    If you want to run all scanners of a certain type, such as SAST, SCA, or DAST,
+    use the CATEGORIES option. All scanners are classified into categories and
+    some may belong to multiple categories. You could run all available SAST 
+    scanners, for example, by passing in SAST as the value for the CATEGORIES
+    option. Values are case-insensitive. Multiple values should be comma-separated.
+    Defaults to "SAST".
+
+    You can specify both SCANNERS and CATEGORIES at the same time. The list of
+    available scanners is filtered by the given SCANNERS and CATEGORIES on the
+    command line, and any matching scanners are then used for the scan.
+
+    By default, findings are displayed as high, moderate, and low. This is the
+    'security' severity format. Findings can also be displayed as errors, warnings,
+    and notes. This is the 'sarif' severity format.
+
+    Exit codes:
+         0 - Clean and successful scan. No errors, warnings, or notes.
+         1 - Bad command, arguments, or options. Scan not completed.
+      8-15 - Scan completed with errors, warnings, or notes.
+         9 - Scan completed with errors (no warnings or notes).
+        10 - Scan completed with warnings (no errors or notes).
+        11 - Scan completed with errors and warnings (no notes).
+        12 - Scan completed with notes (no errors or warnings).
+        13 - Scan completed with errors and notes (no warnings).
+        14 - Scan completed with warnings and notes (no errors).
+        15 - Scan completed with errors, warnings, and notes.
+     >= 16 - Scan aborted due to unexpected error.
+  `,
+  examples: [
+    '$ radar scan ' + '(scan current working directory)'.grey,
+    '$ radar scan . ' + '(scan current working directory)'.grey,
+    '$ radar scan /my/repo/dir ' + '(scan target directory)'.grey,
+    '$ radar scan --output=scan.sarif ' + '(save findings in a file)'.grey,
+    '$ radar scan -o scan.sarif /my/repo/dir ' + '(short versions of options)'.grey,
+    '$ radar scan -s depscan,opengrep ' + '(use only given scanners)'.grey,
+    '$ radar scan -c sca,sast ' + '(use only scanners from given categories)'.grey,
+    '$ radar scan -f security ' + '(displays findings as high, medium, and low)'.grey,
+    '$ radar scan -e warning,note ' + '(treat warnings and notes as errors)'.grey
+  ],
+  run: async (toolbox, args) => {
+    const { log, scanners: availableScanners } = toolbox
+
+    // Set defaults.
+    args.TARGET = path.normalize(args.TARGET ?? process.cwd())
+    args.FORMAT = args.FORMAT ?? 'security'
+    if (args.FORMAT !== 'sarif' && args.FORMAT !== 'security') throw new Error('FORMAT must be one of \'sarif\' or \'security\'')
+    args.CATEGORIES = args.CATEGORIES ?? 'sast'
+
+    // Set scan parameters.
+    // const target  = args.TARGET ? path.resolve(args.TARGET) : "$PWD"      // target to scan
+    const target = path.resolve(args.TARGET) // target to scan
+    const assets = path.join(__dirname, '..', '..', 'scanners') // scanner assets
+    const outdir = fs.mkdtempSync(path.join(os.tmpdir(), 'radar-')) // output directory
+    const outfile = args.OUTPUT ? path.resolve(args.OUTPUT) : undefined // output file, if any
+
+    // Select scanners to use.
+    const scanners = availableScanners
+
+      // Filter by scanner names given by the user:
+      .filter(scanner => {
+        if (!args.SCANNERS) return true
+        return args.SCANNERS.split(',').includes(scanner.name)
+      })
+
+      // Filter by scanner categories given by the user:
+      .filter(scanner => {
+        if (!args.CATEGORIES) return true
+        for (const category of args.CATEGORIES.toUpperCase().split(',')) {
+          if (scanner.categories.includes(category)) return true
+        }
+        return false
+      })
+
+    // Run scanners.
+    let isScanCompleted = true
+    for (const scanner of scanners) {
+      let label = scanner.name
+      const spinner = new Spinner()
+      if (!args.QUIET) spinner.start(label)
+
+      const t = performance.now()
+      const interval = setInterval(() => {
+        const t2 = performance.now()
+        label = `${scanner.name} [${humanize.duration(t2 - t)}]`
+        if (!args.QUIET) spinner.update(label)
+      }, 1000) // 1000 milliseconds = 1 second
+
+      try {
+        let cmd = scanner.cmd
+
+        /* eslint-disable no-template-curly-in-string */
+        cmd = cmd.replaceAll('${target}', target)
+        cmd = cmd.replaceAll('${assets}', path.join(assets, scanner.name))
+        cmd = cmd.replaceAll('${output}', outdir)
+        /* eslint-enable no-template-curly-in-string */
+
+        /* const { stdout } = */ await exec(cmd)
+        if (!args.QUIET) spinner.success(label)
+      } catch (error) {
+        isScanCompleted = false
+        if (!args.QUIET) spinner.error(label)
+        log(`\n${error}`)
+        if (error.stdout) log(error.stdout)
+        if (error.stderr) log(error.stderr)
+      }
+
+      clearInterval(interval)
+    }
+
+    // Process scan findings.
+    let exitCode = 0
+    if (isScanCompleted) {
+      const consolidated = path.join(outdir, 'scan.sarif')
+
+      // Merge all output SARIF files into one.
+      const all = []
+      for (const scanner of scanners) {
+        all.push(path.join(outdir, `${scanner.name}.sarif`))
+      }
+      await sariftools.merge(all, consolidated)
+
+      // Display findings on stdout or write them to destination SARIF file.
+      let sarif = fs.readFileSync(consolidated, 'utf8')
+
+      // Convert the SARIF file into a JS object.
+      try {
+        sarif = JSON.parse(sarif)
+      } catch (error) {
+        log(`\n${error}`)
+      }
+
+      // Treat warnings and notes as errors.
+      if (args.ERRORS) {
+        const levels = args.ERRORS.split(',')
+
+        for (const run of sarif.runs) {
+          if (!run.results) continue
+          for (const result of run.results) {
+            if (levels.includes(result.level)) {
+              result.level = 'error'
+              continue
+            }
+
+            for (const rule of run.tool.driver.rules) {
+              if (rule.id === result.ruleId) {
+                const level = rule.defaultConfiguration.level
+                if (levels.includes(level)) {
+                  rule.defaultConfiguration.level = 'error'
+                }
+                break
+              }
+            }
+          }
+        }
+      }
+
+      // Write findings to the destination SARIF file.
+      if (outfile) {
+        fs.writeFileSync(outfile, JSON.stringify(sarif))
+      }
+
+      // TODO: Upload SARIF to user's Eureka account.
+
+      // Count findings by severity level.
+      const summary = await sariftools.summarize(sarif, target)
+
+      // Display summarized findings.
+      if (!args.QUIET) {
+        log()
+        sariftools.display_findings(summary, args.FORMAT, log)
+        if (outfile) log(`Findings exported to ${consolidated}`)
+        sariftools.display_totals(summary, args.FORMAT, log)
+      }
+
+      // Determine the correct exit code.
+      if (!summary.errors.length && !summary.warnings.length && !summary.notes.length) {
+        exitCode = 0
+      } else {
+        exitCode = 0x8
+        if (summary.errors.length > 0) exitCode |= 0x1
+        if (summary.warnings.length > 0) exitCode |= 0x2
+        if (summary.notes.length > 0) exitCode |= 0x4
+      }
+    } else {
+      exitCode = 0x10
+      if (!args.QUIET) log('Scan NOT completed!')
+    }
+
+    // Clean up.
+    fs.rmSync(outdir, { recursive: true, force: true })
+
+    return exitCode
+  }
+}

package/src/commands/scanners.js

@@ -0,0 +1,15 @@
+module.exports = {
+  summary: 'display available scanners',
+  description: `
+    Displays available scanners.
+  `,
+  examples: [
+    '$ radar scanners'
+  ],
+  run: async (toolbox, args) => {
+    const { log, scanners } = toolbox
+    for (const scanner of scanners) {
+      log(`${scanner.name}: ${scanner.title} [${scanner.categories.join()}] - ${scanner.description}`)
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,21 @@
+const { build } = require('@persistr/clif')
+const pkg = require('../package.json')
+const commands = require('./commands')
+
+// Plugins.
+const plugins = {
+  settings: require('@persistr/clif-plugin-settings')
+}
+
+module.exports = {
+  build: (options) => {
+    // Configure the Radar CLI.
+    return build(pkg.name, 'radar', pkg.repository.url.replace(/\.git$/, ''))
+      .plugins(Object.values({ ...plugins, ...options?.plugins }))
+      .toolbox(options?.toolbox)
+      .version(pkg.version, '-v, --version')
+      .description(`${pkg.description}\n${pkg.homepage}`)
+      .commands(commands)
+      .done()
+  }
+}

package/src/plugins/scanners.js

@@ -0,0 +1,12 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const TOML = require('smol-toml')
+
+const data = fs.readFileSync(path.join(__dirname, '..', '..', 'scanners', 'scanners.toml'), 'utf8')
+const config = TOML.parse(data)
+
+module.exports = {
+  toolbox: {
+    scanners: config.scanners
+  }
+}

package/src/util/humanize.js

@@ -0,0 +1,23 @@
+const humanizeDuration = require('humanize-duration')
+
+const humanizer = humanizeDuration.humanizer({
+  language: 'shortEn',
+  languages: {
+    shortEn: {
+      y: () => 'y',
+      mo: () => 'mo',
+      w: () => 'w',
+      d: () => 'd',
+      h: () => 'h',
+      m: () => 'm',
+      s: () => 's',
+      ms: () => 'ms'
+    }
+  }
+})
+
+module.exports = {
+  duration: (duration) => {
+    return humanizer(duration, { units: ['y', 'mo', 'w', 'd', 'h', 'm', 's'], round: true, spacer: '', delimiter: ' ' })
+  }
+}

package/src/util/sarif/display_findings.js

@@ -0,0 +1,6 @@
+const levels = require('./levels')
+module.exports = async (summary, format, log) => {
+  for (const finding of summary.notes) log(`${finding.artifact.name}:${finding.artifact.line}: ` + `${levels[format].single.note}`.bold + `${levels[format].single.suffix}:` + ` ${finding.message}\n`)
+  for (const finding of summary.warnings) log(`${finding.artifact.name}:${finding.artifact.line}: ` + `${levels[format].single.warning}`.bold.yellow + `${levels[format].single.suffix}:` + ` ${finding.message}\n`)
+  for (const finding of summary.errors) log(`${finding.artifact.name}:${finding.artifact.line}: ` + `${levels[format].single.error}`.bold.red + `${levels[format].single.suffix}:` + ` ${finding.message}\n`)
+}

package/src/util/sarif/display_totals.js

@@ -0,0 +1,5 @@
+const levels = require('./levels')
+module.exports = async (summary, format, log) => {
+  const total = summary.errors.length + summary.warnings.length + summary.notes.length
+  log(`${total} ${total === 1 ? levels[format].total.issue : levels[format].total.issues}: ${summary.errors.length} ` + `${levels[format].total.error}`.red.bold + `, ${summary.warnings.length} ` + `${levels[format].total.warning}`.yellow.bold + `, ${summary.notes.length} ` + `${levels[format].total.note}` + '.')
+}

package/src/util/sarif/index.js

@@ -0,0 +1,6 @@
+module.exports = {
+  merge: require('./merge'),
+  summarize: require('./summarize'),
+  display_findings: require('./display_findings'),
+  display_totals: require('./display_totals')
+}

package/src/util/sarif/levels.js

@@ -0,0 +1,32 @@
+module.exports = {
+  sarif: {
+    single: {
+      error: 'error',
+      warning: 'warning',
+      note: 'note',
+      suffix: ''
+    },
+    total: {
+      issue: 'vulnerability',
+      issues: 'vulnerabilities',
+      error: 'error(s)',
+      warning: 'warning(s)',
+      note: 'note(s)'
+    }
+  },
+  security: {
+    single: {
+      error: 'high',
+      warning: 'moderate',
+      note: 'low',
+      suffix: ' severity'
+    },
+    total: {
+      issue: 'vulnerability',
+      issues: 'vulnerabilities',
+      error: 'high',
+      warning: 'moderate',
+      note: 'low'
+    }
+  }
+}

package/src/util/sarif/merge.js

@@ -0,0 +1,52 @@
+/*
+const util = require('node:util')
+const exec = util.promisify(require('node:child_process').exec)
+const multitoolPath = require('@microsoft/sarif-multitool')
+const path = require('node:path')
+module.exports = {
+  merge: async (outdir) => {
+    const cmd = `${multitoolPath} merge ${path.join(outdir, '*.sarif')} --recurse false --output-directory=${outdir} --output-file=scan.sarif`
+    const { stdout, stderr } = await exec(cmd)
+  }
+}
+*/
+
+const fs = require('node:fs')
+module.exports = async (files, outfile) => {
+  const sarif = {
+    version: '2.1.0',
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    runs: []
+  }
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf8')
+    const scan = JSON.parse(content)
+    for (const run of scan.runs) {
+      const tool = {
+        driver: {
+          name: run.tool.driver.name,
+          semanticVersion: run.tool.driver.semanticVersion,
+          informationUri: run.tool.driver.informationUri,
+          properties: run.tool.driver.properties,
+          rules: []
+        }
+      }
+
+      const rules = new Map()
+      for (const result of run.results) {
+        rules.set(result.ruleId, true)
+      }
+
+      for (const rule of run.tool.driver.rules) {
+        if (rules.has(rule.id)) {
+          tool.driver.rules.push(rule)
+        }
+      }
+
+      sarif.runs.push({ tool, invocations: run.invocations, results: run.results })
+    }
+  }
+
+  fs.writeFileSync(outfile, JSON.stringify(sarif))
+}

package/src/util/sarif/summarize.js

@@ -0,0 +1,40 @@
+const path = require('node:path')
+module.exports = (sarif, dir) => {
+  // Summarize findings by severity level.
+  const summary = { errors: [], warnings: [], notes: [] }
+  for (const run of sarif.runs) {
+    if (!run.results) continue
+    for (const result of run.results) {
+      let file = path.relative('/app', result.locations[0].physicalLocation.artifactLocation.uri)
+      file = path.join(dir, file)
+      file = path.relative(process.cwd(), file)
+
+      const finding = {
+        tool: run.tool.driver.name,
+        message: result.message.text,
+        artifact: {
+          name: file,
+          line: result.locations[0].physicalLocation.region.startLine
+        }
+      }
+
+      if (result.level === 'error' || result.level === 'warning' || result.level === 'note') {
+        finding.level = result.level
+        summary[`${finding.level}s`].push(finding)
+        continue
+      }
+
+      for (const rule of run.tool.driver.rules) {
+        if (rule.id === result.ruleId) {
+          const level = rule.defaultConfiguration.level
+          if (level === 'error' || level === 'warning' || level === 'note') {
+            finding.level = level
+            summary[`${finding.level}s`].push(finding)
+          }
+          break
+        }
+      }
+    }
+  }
+  return summary
+}