boostsecurityio/scanner

A shareable package of CircleCI configuration to integrate with scanner, written by boostsecurityio

Community

Orb Quick Start Guide
Usage Examples
Jobs
- scan
Commands
- install
- scan
Orb Source

Orbs
boostsecurityio/scanner@4.1.1

boostsecurityio/scanner@4.1.1

Sections

Executes the Boost Security Scanner cli tool to scan repositories for vulnerabilities and uploads results to the Boost API.

Created: May 27, 2022Version Published: March 4, 2024Releases: 12

Org Usage:

< 25

Homepage:

https://www.boostsecurity.io

Source:

https://github.com/boostsecurityio/boostsec-scanner-circleci

See Orb Licensing

Orb Quick Start Guide

Use CircleCI version 2.1 at the top of your .circleci/config.yml file.

1
version: 2.1

Add the orbs stanza below your version, invoking the orb:

1
2
orbs:
  scanner: boostsecurityio/scanner@4.1.1

Use scanner elements in your existing workflows and jobs.

Opt-in to use of uncertified orbs on your organization’s Security settings page.

Usage Examples

command

Add the boost scanner as a pipeline job command.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
version: '2.1'
orbs:
  boost-security-scanner: boostsecurityio/scanner@x.y.z
jobs:
  scan:
    executor: default
    steps:
      - checkout
      - boost-security-scanner/scan:
          api_token_var: BOOST_API_TOKEN
          registry_module: scanners/boostsecurityio/native-scanner
workflows:
  build:
    jobs:
      - test
      - scan:
          context: boost-security
      - push:
          requires:
            - test
  version: 2

install

Install the boost scanner in your ci environment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
version: '2.1'
orbs:
  boost-security-scanner: boostsecurityio/scanner@x.y.z
jobs:
  scan:
    executor: default
    steps:
      - checkout
      - boost-security-scanner/install
      - run: boost version
workflows:
  build:
    jobs:
      - test
      - scan:
          context: boost-security
      - push:
          requires:
            - test
  version: 2

job

Add the boost scanner as a pipeline workflow job. Prior to adding this step, you following environment variables should be defined either in a context object or through repository environment vars. BOOST_API_TOKEN -- The boost api token

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
version: '2.1'
orbs:
  boost-security-scanner: boostsecurityio/scanner@x.y.z
workflows:
  build:
    jobs:
      - test
      - boost-security-scanner/scan:
          api_token_var: BOOST_API_TOKEN
          context: boost-security
          name: scan
          registry_module: scanners/boostsecurityio/native-scanner
      - push:
          requires:
            - test
  version: 2

Jobs

scan

Scans the git repository for security issues or violations and uploads the results to the Boost Security API.

Show job Source

Commands

install

Scans the git repository for security issues or violations and uploads the results to the Boost Security API.

Show command Source

PARAMETER	DESCRIPTION	REQUIRED	DEFAULT	TYPE
cli_version CLI version to download, may be Major, Major.Minor or Major.Minor.Patch	CLI version to download, may be Major, Major.Minor or Major.Minor.Patch	No	'1' type: string	string

scan

Scans the git repository for security issues or violations and uploads the results to the Boost Security API.

Show command Source

PARAMETER	DESCRIPTION	REQUIRED	DEFAULT	TYPE
additional_args Additional arguments to pass to boost cli	Additional arguments to pass to boost cli	No	'' type: string	string
api_enabled Optional Boost API URL environment variable name	Optional Boost API URL environment variable name	No	true type: boolean	boolean
api_endpoint Optional Boost API URL environment variable name	Optional Boost API URL environment variable name	No	'' type: string	string
api_token Boost API token environment variable name	Boost API token environment variable name	No	BOOST_API_TOKEN type: env_var_name	env_var_name
cli_version CLI version to download, may be Major, Major.Minor or Major.Minor.Patch	CLI version to download, may be Major, Major.Minor or Major.Minor.Patch	No	'1' type: string	string
ignore_failure Ignore any exception returned by the scanner cli	Ignore any exception returned by the scanner cli	No	false type: boolean	boolean
log_level Set the cli logging level	Set the cli logging level	No	'' type: string	string
main_branch Optional override for main branch detection	Optional override for main branch detection	No	'' type: string	string
pre_scan_cmd Optional command to run before scanning	Optional command to run before scanning	No	'' type: string	string
registry_module Module within the scanner registry to execute Required	Module within the scanner registry to execute	Yes	- type: string	string
scan_label Optional identifier to identify a a monorepo component	Optional identifier to identify a a monorepo component	No	'' type: string	string
scan_path Optional relative path to scan. Must be used with a scan_label.	Optional relative path to scan. Must be used with a scan_label.	No	'' type: string	string
scan_timeout Maximum amount of time a diff scan should complete in	Maximum amount of time a diff scan should complete in	No	'' type: string	string
scanner_id Optional identifier to uniquely identify the scanner	Optional identifier to uniquely identify the scanner	No	'' type: string	string

Orb Source

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
    Executes the Boost Security Scanner cli tool to scan repositories for vulnerabilities and uploads results to the Boost API.
display:
    home_url: https://www.boostsecurity.io
    source_url: https://github.com/boostsecurityio/boostsec-scanner-circleci
commands:
    install:
        description: |
            Scans the git repository for security issues or violations and uploads the results to the Boost Security API.
        parameters:
            cli_version:
                default: "1"
                description: |
                    CLI version to download, may be Major, Major.Minor or Major.Minor.Patch
                type: string
        steps:
            - run:
                command: |
                    [ -w /usr/local/bin ] && SUDO="" || SUDO=sudo
                    /bin/echo "${CLI_WRAPPER}" | ${SUDO} tee /usr/local/bin/boost > /dev/null
                    ${SUDO} chmod 755 /usr/local/bin/boost
                environment:
                    CLI_WRAPPER: |
                        #!/bin/bash

                        log.info ()
                        { # $@=message
                          printf "$(date +'%H:%M:%S') [\033[34m%s\033[0m] %s\n" "INFO" "${*}";
                        }

                        log.error ()
                        { # $@=message
                          printf "$(date +'%H:%M:%S') [\033[31m%s\033[0m] %s\n" "ERROR" "${*}";
                        }

                        git.ls_remote ()
                        {
                          git ls-remote --symref origin HEAD \
                            | awk '/^ref:/{sub(/refs\/heads\//, "", $2); print $2}'
                        }

                        init.config ()
                        {
                          log.info "initializing configuration"

                          export BOOST_TMP_DIR=${BOOST_TMP_DIR:-${WORKSPACE_TMP:-${TMPDIR:-/tmp}}}
                          export BOOST_EXE=${BOOST_EXE:-${BOOST_TMP_DIR}/boost-cli/latest}

                          export BOOST_CLI_URL=${BOOST_CLI_URL:-https://assets.build.boostsecurity.io}
                                 BOOST_CLI_URL=${BOOST_CLI_URL%*/}
                          export BOOST_DOWNLOAD_URL=${BOOST_DOWNLOAD_URL:-${BOOST_CLI_URL}/boost-cli/get-boost-cli}

                          export BOOST_GIT_MAIN_BRANCH
                                 BOOST_GIT_MAIN_BRANCH=${BOOST_GIT_MAIN_BRANCH:-$(git.ls_remote)}

                          init.ci.config
                        }

                        init.ci.config ()
                        {
                          if [ "${CIRCLE_BRANCH:-}" != "${BOOST_GIT_MAIN_BRANCH}" ]; then
                            export BOOST_GIT_BASE=${BOOST_GIT_MAIN_BRANCH}

                            if [ -z "${CIRCLE_PULL_REQUEST:-}" ]; then
                              log.info "non-main branch without a pull-request is not supported"
                              exit 0
                            fi
                          fi
                        }

                        init.cli ()
                        {
                          mkdir -p "${BOOST_TMP_DIR}"
                          curl --silent "${BOOST_DOWNLOAD_URL}" | bash
                        }

                        main.install ()
                        {
                          init.config
                          init.cli
                        }

                        if ! ${BATS_ENABLED:-false}; then
                          set -e
                          set -o pipefail
                          set -u

                          if ! test -d .git; then
                            log.error "boost must be run at the root of your project repository"
                            exit 1
                          fi

                          main.install

                          set +u
                          exec ${BOOST_EXE} "${@}"
                        fi
                name: Installing boost cli
    scan:
        description: |
            Scans the git repository for security issues or violations and uploads the results to the Boost Security API.
        parameters:
            additional_args:
                default: ""
                description: |
                    Additional arguments to pass to boost cli
                type: string
            api_enabled:
                default: true
                description: |
                    Optional Boost API URL environment variable name
                type: boolean
            api_endpoint:
                default: ""
                description: |
                    Optional Boost API URL environment variable name
                type: string
            api_token:
                default: BOOST_API_TOKEN
                description: |
                    Boost API token environment variable name
                type: env_var_name
            cli_version:
                default: "1"
                description: |
                    CLI version to download, may be Major, Major.Minor or Major.Minor.Patch
                type: string
            ignore_failure:
                default: false
                description: |
                    Ignore any exception returned by the scanner cli
                type: boolean
            log_level:
                default: ""
                description: |
                    Set the cli logging level
                type: string
            main_branch:
                default: ""
                description: |
                    Optional override for main branch detection
                type: string
            pre_scan_cmd:
                default: ""
                description: |
                    Optional command to run before scanning
                type: string
            registry_module:
                description: |
                    Module within the scanner registry to execute
                type: string
            scan_label:
                default: ""
                description: |
                    Optional identifier to identify a a monorepo component
                type: string
            scan_path:
                default: ""
                description: |
                    Optional relative path to scan. Must be used with a scan_label.
                type: string
            scan_timeout:
                default: ""
                description: |
                    Maximum amount of time a diff scan should complete in
                type: string
            scanner_id:
                default: ""
                description: |
                    Optional identifier to uniquely identify the scanner
                type: string
        steps:
            - run:
                command: |
                    #!/bin/bash

                    log.info ()
                    { # $@=message
                      printf "$(date +'%H:%M:%S') [\033[34m%s\033[0m] %s\n" "INFO" "${*}";
                    }

                    log.error ()
                    { # $@=message
                      printf "$(date +'%H:%M:%S') [\033[31m%s\033[0m] %s\n" "ERROR" "${*}";
                    }

                    git.ls_remote ()
                    {
                      git ls-remote --symref origin HEAD \
                        | awk '/^ref:/{sub(/refs\/heads\//, "", $2); print $2}'
                    }

                    init.config ()
                    {
                      log.info "initializing configuration"

                      export BOOST_TMP_DIR=${BOOST_TMP_DIR:-${WORKSPACE_TMP:-${TMPDIR:-/tmp}}}
                      export BOOST_EXE=${BOOST_EXE:-${BOOST_TMP_DIR}/boost-cli/latest}

                      export BOOST_CLI_URL=${BOOST_CLI_URL:-https://assets.build.boostsecurity.io}
                             BOOST_CLI_URL=${BOOST_CLI_URL%*/}
                      export BOOST_DOWNLOAD_URL=${BOOST_DOWNLOAD_URL:-${BOOST_CLI_URL}/boost-cli/get-boost-cli}

                      export BOOST_GIT_MAIN_BRANCH
                             BOOST_GIT_MAIN_BRANCH=${BOOST_GIT_MAIN_BRANCH:-$(git.ls_remote)}

                      init.ci.config
                    }

                    init.ci.config ()
                    {
                      export BOOST_API_TOKEN=${!BOOST_API_TOKEN_VAR:-}

                      if [ "${CIRCLE_BRANCH:-}" != "${BOOST_GIT_MAIN_BRANCH}" ]; then
                        export BOOST_GIT_BASE=${BOOST_GIT_MAIN_BRANCH}

                        if [ -z "${CIRCLE_PULL_REQUEST:-}" ]; then
                          log.info "non-main branch without a pull-request is not supported"
                          exit 0
                        fi
                      fi
                    }

                    init.cli ()
                    {
                      mkdir -p "${BOOST_TMP_DIR}"
                      curl --silent "${BOOST_DOWNLOAD_URL}" | bash
                    }

                    main.scan ()
                    {
                      init.config
                      init.cli

                      # shellcheck disable=SC2086
                      exec ${BOOST_EXE} scan repo ${BOOST_CLI_ARGUMENTS:-}
                    }

                    if ! ${BATS_ENABLED:-false}; then
                      set -e
                      set -o pipefail
                      set -u

                      main.scan
                    fi
                environment:
                    BOOST_API_ENABLED: <<parameters.api_enabled>>
                    BOOST_API_ENDPOINT: <<parameters.api_endpoint>>
                    BOOST_API_TOKEN_VAR: <<parameters.api_token>>
                    BOOST_CLI_ARGUMENTS: <<parameters.additional_args>>
                    BOOST_CLI_VERSION: <<parameters.cli_version>>
                    BOOST_DIFF_SCAN_TIMEOUT: <<parameters.scan_timeout>>
                    BOOST_GIT_MAIN_BRANCH: <<parameters.main_branch>>
                    BOOST_IGNORE_FAILURE: <<parameters.ignore_failure>>
                    BOOST_LOG_LEVEL: <<parameters.log_level>>
                    BOOST_PRE_SCAN: <<parameters.pre_scan_cmd>>
                    BOOST_SCAN_LABEL: <<parameters.scan_label>>
                    BOOST_SCAN_PATH: <<parameters.scan_path>>
                    BOOST_SCANNER_ID: <<parameters.scanner_id>>
                    BOOST_SCANNER_REGISTRY_MODULE: <<parameters.registry_module>>
                name: Scanning repository
                no_output_timeout: 120m
jobs:
    scan:
        description: |
            Scans the git repository for security issues or violations and uploads the results to the Boost Security API.
        machine:
            docker_layer_caching: <<parameters.executor_docker_layer_caching>>
            image: ubuntu-2204:current
        parameters:
            additional_args:
                default: ""
                description: |
                    Additional arguments to pass to boost cli
                type: string
            api_enabled:
                default: true
                description: |
                    Optional Boost API URL environment variable name
                type: boolean
            api_endpoint:
                default: ""
                description: |
                    Optional Boost API URL environment variable name
                type: string
            api_token:
                default: BOOST_API_TOKEN
                description: |
                    Boost API token environment variable name
                type: env_var_name
            cli_version:
                default: "1"
                description: |
                    CLI version to download, may be Major, Major.Minor or Major.Minor.Patch
                type: string
            executor_docker_layer_caching:
                default: true
                description: |
                    Enable or disable executor's docker layer caching
                type: boolean
            ignore_failure:
                default: false
                description: |
                    Ignore any exception returned by the scanner cli
                type: boolean
            log_level:
                default: ""
                description: |
                    Set the cli logging level
                type: string
            main_branch:
                default: ""
                description: |
                    Optional override for main branch detection
                type: string
            pre_scan_cmd:
                default: ""
                description: |
                    Optional command to run before scanning
                type: string
            registry_module:
                description: |
                    Module within the scanner registry to execute
                type: string
            scan_label:
                default: ""
                description: |
                    Optional identifier to identify a a monorepo component
                type: string
            scan_path:
                default: ""
                description: |
                    Optional relative path to scan. Must be used with a scan_label.
                type: string
            scan_timeout:
                default: ""
                description: |
                    Maximum amount of time a diff scan should complete in
                type: string
            scanner_id:
                default: ""
                description: |
                    Optional identifier to uniquely identify the scanner
                type: string
        steps:
            - checkout
            - scan:
                additional_args: <<parameters.additional_args>>
                api_enabled: <<parameters.api_enabled>>
                api_endpoint: <<parameters.api_endpoint>>
                api_token: <<parameters.api_token>>
                cli_version: <<parameters.cli_version>>
                ignore_failure: <<parameters.ignore_failure>>
                log_level: <<parameters.log_level>>
                main_branch: <<parameters.main_branch>>
                pre_scan_cmd: <<parameters.pre_scan_cmd>>
                registry_module: <<parameters.registry_module>>
                scan_label: <<parameters.scan_label>>
                scan_path: <<parameters.scan_path>>
                scan_timeout: <<parameters.scan_timeout>>
                scanner_id: <<parameters.scanner_id>>
examples:
    command:
        description: |
            Add the boost scanner as a pipeline job command.
        usage:
            version: "2.1"
            orbs:
                boost-security-scanner: boostsecurityio/scanner@x.y.z
            jobs:
                scan:
                    executor: default
                    steps:
                        - checkout
                        - boost-security-scanner/scan:
                            api_token_var: BOOST_API_TOKEN
                            registry_module: scanners/boostsecurityio/native-scanner
            workflows:
                build:
                    jobs:
                        - test
                        - scan:
                            context: boost-security
                        - push:
                            requires:
                                - test
                version: 2
    install:
        description: |
            Install the boost scanner in your ci environment
        usage:
            version: "2.1"
            orbs:
                boost-security-scanner: boostsecurityio/scanner@x.y.z
            jobs:
                scan:
                    executor: default
                    steps:
                        - checkout
                        - boost-security-scanner/install
                        - run: boost version
            workflows:
                build:
                    jobs:
                        - test
                        - scan:
                            context: boost-security
                        - push:
                            requires:
                                - test
                version: 2
    job:
        description: |
            Add the boost scanner as a pipeline workflow job.

            Prior to adding this step, you following environment variables should be
            defined either in a context object or through repository environment vars.

            BOOST_API_TOKEN -- The boost api token
        usage:
            version: "2.1"
            orbs:
                boost-security-scanner: boostsecurityio/scanner@x.y.z
            workflows:
                build:
                    jobs:
                        - test
                        - boost-security-scanner/scan:
                            api_token_var: BOOST_API_TOKEN
                            context: boost-security
                            name: scan
                            registry_module: scanners/boostsecurityio/native-scanner
                        - push:
                            requires:
                                - test
                version: 2

Developer Updates

Get tips to optimize your builds

Or join our research panel and give feedback

By submitting this form, you are agreeing to ourTerms of UseandPrivacy Policy.