github.com/jaylevin/jenkins-library@v1.230.4/resources/metadata/fortifyExecuteScan.yaml (about) 1 metadata: 2 name: fortifyExecuteScan 3 description: This step executes a Fortify scan on the specified project to perform static code analysis and check the source code for security flaws. 4 longDescription: |- 5 This step executes a Fortify scan on the specified project to perform static code analysis and check the source code for security flaws. 6 7 The Fortify step triggers a scan locally on your Jenkins within a docker container so finally you have to supply a docker image with a Fortify SCA 8 and Java plus Maven / Gradle or alternatively Python installed into it for being able to perform any scans. 9 !!! hint "Scanning MTA projects" 10 Build type `maven` requires a so called aggregator pom which includes all modules to be scanned. If used in a mta-project which includes non-java submodules as maven dependency (e.g. node via frontend-maven-plugin), exclude those by specifying java path explicitly, e.g. `java/**/src/main/java/**/*`. 11 12 Besides triggering a scan the step verifies the results after they have been uploaded and processed by the Fortify SSC. By default the following KPIs are enforced: 13 * All issues must be audited from the Corporate Security Requirements folder. 14 * All issues must be audited from the Audit All folder. 15 * At least one issue per category must be audited from the Spot Checks of Each Category folder. 16 * Nothing needs to be audited from the Optional folder. 17 18 spec: 19 inputs: 20 secrets: 21 - name: fortifyCredentialsId 22 description: Jenkins 'Secret text' credentials ID containing token to authenticate to Fortify SSC. 23 type: jenkins 24 - name: githubTokenCredentialsId 25 description: Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub. 26 type: jenkins 27 resources: 28 - name: commonPipelineEnvironment 29 resourceSpec: 30 type: piperEnvironment 31 - name: buildDescriptor 32 type: stash 33 - name: deployDescriptor 34 type: stash 35 - name: tests 36 type: stash 37 - name: opensourceConfiguration 38 type: stash 39 params: 40 - name: additionalScanParameters 41 description: List of additional scan parameters to be used for Fortify sourceanalyzer command execution. 42 type: "[]string" 43 scope: 44 - PARAMETERS 45 - STAGES 46 - STEPS 47 - name: assignees 48 description: Defines the assignees for the Github Issue created/updated with the results of the scan as a list of login names. 49 scope: 50 - PARAMETERS 51 - STAGES 52 - STEPS 53 type: "[]string" 54 default: [] 55 - name: authToken 56 type: string 57 description: "The FortifyToken to use for authentication" 58 scope: 59 - PARAMETERS 60 - STAGES 61 - STEPS 62 mandatory: true 63 secret: true 64 resourceRef: 65 - name: fortifyCredentialsId 66 type: secret 67 - type: vaultSecret 68 name: fortifyVaultSecretName 69 default: fortify 70 - name: buildDescriptorExcludeList 71 type: "[]string" 72 description: "List of build descriptors and therefore modules to exclude from the scan and assessment activities." 73 scope: 74 - PARAMETERS 75 - STAGES 76 - STEPS 77 default: ["unit-tests/pom.xml", "integration-tests/pom.xml"] 78 - name: customScanVersion 79 type: string 80 description: Custom version of the Fortify project used as source. 81 longDescription: |- 82 Defines a custom version for the Fortify scan which deviates from the typical versioning pattern using [`version`](#version) and [`versioningModel`](#versioningModel). 83 It allows to set non-numeric versions as well and supersedes the value of [`version`](#version) which is calculated automatically. 84 The parameter is also used by other scan steps (e.g. Detect, Sonar, WhiteSource) and thus allows a common custom version across scan tools. 85 scope: 86 - GENERAL 87 - PARAMETERS 88 - STAGES 89 - STEPS 90 - name: githubToken 91 description: "GitHub personal access token as per 92 https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line" 93 scope: 94 - GENERAL 95 - PARAMETERS 96 - STAGES 97 - STEPS 98 type: string 99 secret: true 100 aliases: 101 - name: access_token 102 resourceRef: 103 - name: githubTokenCredentialsId 104 type: secret 105 - type: vaultSecret 106 default: github 107 name: githubVaultSecretName 108 - name: autoCreate 109 type: bool 110 description: 111 "Whether Fortify project and project version shall be implicitly auto created in case they 112 cannot be found in the backend" 113 scope: 114 - PARAMETERS 115 - STAGES 116 - STEPS 117 - name: modulePath 118 type: string 119 description: "Allows providing the path for the module to scan" 120 scope: 121 - PARAMETERS 122 - STAGES 123 - STEPS 124 default: "./" 125 - name: pythonRequirementsFile 126 type: string 127 description: 128 "The requirements file used in `buildTool: 'pip'` to populate 129 the build environment with the necessary dependencies" 130 scope: 131 - PARAMETERS 132 - STAGES 133 - STEPS 134 - name: autodetectClasspath 135 type: bool 136 description: "Whether the classpath is automatically determined via build tool i.e. maven or pip or not at all" 137 scope: 138 - PARAMETERS 139 - STAGES 140 - STEPS 141 default: true 142 - name: mustAuditIssueGroups 143 type: string 144 description: "Comma separated list of issue groups that must be audited completely" 145 scope: 146 - PARAMETERS 147 - STAGES 148 - STEPS 149 default: "Corporate Security Requirements, Audit All" 150 - name: spotAuditIssueGroups 151 type: string 152 description: 153 "Comma separated list of issue groups that are spot checked and for which `spotCheckMinimum` 154 audited issues are enforced" 155 scope: 156 - PARAMETERS 157 - STAGES 158 - STEPS 159 default: "Spot Checks of Each Category" 160 - name: pythonRequirementsInstallSuffix 161 type: string 162 description: 163 "The suffix for the command used to install the requirements file in `buildTool: 'pip'` to populate 164 the build environment with the necessary dependencies" 165 scope: 166 - PARAMETERS 167 - STAGES 168 - STEPS 169 - name: pythonVersion 170 type: string 171 description: "Python version to be used in `buildTool: 'pip'`" 172 scope: 173 - GENERAL 174 - PARAMETERS 175 - STAGES 176 - STEPS 177 default: python3 178 - name: uploadResults 179 type: bool 180 description: "Whether results shall be uploaded or not" 181 scope: 182 - PARAMETERS 183 - STAGES 184 - STEPS 185 default: true 186 - name: version 187 aliases: 188 - name: fortifyProjectVersion 189 deprecated: true 190 type: string 191 description: Version used in conjunction with [`versioningModel`](#versioningModel) to identify the Fortify project to be created and used for results aggregation. 192 longDescription: |- 193 Version used in conjunction with [`versioningModel`](#versioningModel) to identify the Fortify project to be created and used for results aggregation. 194 This is usually determined automatically based on the information in the buildTool specific build descriptor file. 195 scope: 196 - GENERAL 197 - PARAMETERS 198 - STAGES 199 - STEPS 200 resourceRef: 201 - name: commonPipelineEnvironment 202 param: artifactVersion 203 - name: buildDescriptorFile 204 type: string 205 conditions: 206 - conditionRef: strings-equal 207 params: 208 - name: buildTool 209 value: maven 210 description: "Path to the build descriptor file addressing the module/folder to be scanned." 211 scope: 212 - PARAMETERS 213 - STAGES 214 - STEPS 215 default: ./pom.xml 216 - name: buildDescriptorFile 217 type: string 218 conditions: 219 - conditionRef: strings-equal 220 params: 221 - name: buildTool 222 value: pip 223 description: "Path to the build descriptor file addressing the module/folder to be scanned." 224 scope: 225 - PARAMETERS 226 - STAGES 227 - STEPS 228 default: ./setup.py 229 - name: buildDescriptorFile 230 type: string 231 conditions: 232 - conditionRef: strings-equal 233 params: 234 - name: buildTool 235 value: gradle 236 description: "Path to the build descriptor file addressing the module/folder to be scanned." 237 scope: 238 - PARAMETERS 239 - STAGES 240 - STEPS 241 default: ./build.gradle 242 - name: commitId 243 description: "Set the Git commit ID for identifying artifacts throughout the scan." 244 resourceRef: 245 - name: commonPipelineEnvironment 246 param: git/commitId 247 scope: 248 - PARAMETERS 249 - STAGES 250 - STEPS 251 type: string 252 - name: commitMessage 253 description: "Set the Git commit message for identifying pull request merges throughout the scan." 254 resourceRef: 255 - name: commonPipelineEnvironment 256 param: git/commitMessage 257 scope: 258 - PARAMETERS 259 - STAGES 260 - STEPS 261 type: string 262 - name: githubApiUrl 263 description: "Set the GitHub API URL." 264 scope: 265 - GENERAL 266 - PARAMETERS 267 - STAGES 268 - STEPS 269 type: string 270 default: "https://api.github.com" 271 - name: owner 272 aliases: 273 - name: githubOrg 274 description: "Set the GitHub organization." 275 resourceRef: 276 - name: commonPipelineEnvironment 277 param: github/owner 278 scope: 279 - GENERAL 280 - PARAMETERS 281 - STAGES 282 - STEPS 283 type: string 284 - name: repository 285 aliases: 286 - name: githubRepo 287 description: "Set the GitHub repository." 288 resourceRef: 289 - name: commonPipelineEnvironment 290 param: github/repository 291 scope: 292 - GENERAL 293 - PARAMETERS 294 - STAGES 295 - STEPS 296 type: string 297 - name: memory 298 type: string 299 description: "The amount of memory granted to the translate/scan executions" 300 scope: 301 - PARAMETERS 302 - STAGES 303 - STEPS 304 default: "-Xmx4G -Xms512M" 305 - name: updateRulePack 306 type: bool 307 description: "Whether the rule pack shall be updated and pulled from Fortify SSC before scanning or not" 308 scope: 309 - PARAMETERS 310 - STAGES 311 - STEPS 312 default: true 313 - name: reportDownloadEndpoint 314 aliases: 315 - name: fortifyReportDownloadEndpoint 316 type: string 317 description: "Fortify SSC endpoint for Report downloads" 318 scope: 319 - GENERAL 320 - PARAMETERS 321 - STAGES 322 - STEPS 323 default: "/transfer/reportDownload.html" 324 - name: pollingMinutes 325 type: int 326 description: 327 "The number of minutes for which an uploaded FPR artifact''s status is being polled to finish 328 queuing/processing, if exceeded polling will be stopped and an error will be thrown" 329 scope: 330 - PARAMETERS 331 - STAGES 332 - STEPS 333 default: 30 334 - name: quickScan 335 type: bool 336 description: 337 "Whether a quick scan should be performed, please consult the related Fortify documentation on 338 JAM on the impact of this setting" 339 scope: 340 - PARAMETERS 341 - STAGES 342 - STEPS 343 default: false 344 - name: translate 345 type: string 346 description: 347 "Options for translate phase of Fortify. Most likely, you do not need to set this parameter. 348 See src, exclude. If `'src'` and `'exclude'` are set they are automatically used. Technical details: 349 It has to be a JSON string of list of maps with required key `'src'`, and optional keys `'exclude'`, 350 `'libDirs'`, `'aspnetcore'`, and `'dotNetCoreVersion'`" 351 scope: 352 - PARAMETERS 353 - STAGES 354 - STEPS 355 - name: src 356 type: "[]string" 357 description: 358 "A list of source directories to scan. Wildcards can be used, e.g., `'src/main/java/**/*'`. 359 If `'translate'` is set, this will ignored. The default value for `buildTool: 'maven'` is 360 `['**/*.xml', '**/*.html', '**/*.jsp', '**/*.js', '**/src/main/resources/**/*', '**/src/main/java/**/*', 361 '**/target/main/java/**/*', '**/target/main/resources/**/*', '**/target/generated-sources/**/*']`, for 362 `buildTool: 'pip'` it is `['./**/*']`." 363 scope: 364 - PARAMETERS 365 - STAGES 366 - STEPS 367 - name: exclude 368 type: "[]string" 369 description: 370 "A list of directories/files to be excluded from the scan. Wildcards can be used, e.g., 371 `'**/Test.java'`. If `translate` is set, this will ignored. The default value for `buildTool: 'maven'` is 372 `['**/src/test/**/*']`, for `buildTool: 'pip'` it is `['./**/tests/**/*', './**/setup.py']`." 373 scope: 374 - PARAMETERS 375 - STAGES 376 - STEPS 377 - name: apiEndpoint 378 aliases: 379 - name: fortifyApiEndpoint 380 type: string 381 description: "Fortify SSC endpoint used for uploading the scan results and checking the audit state" 382 scope: 383 - GENERAL 384 - PARAMETERS 385 - STAGES 386 - STEPS 387 default: "/api/v1" 388 - name: reportType 389 type: string 390 description: The type of report to be generated 391 scope: 392 - PARAMETERS 393 - STAGES 394 - STEPS 395 default: "PDF" 396 - name: pythonAdditionalPath 397 type: "[]string" 398 description: "A list of additional paths which can be used in `buildTool: 'pip'` for customization purposes" 399 scope: 400 - PARAMETERS 401 - STAGES 402 - STEPS 403 default: ["./lib", "."] 404 deprecationMessage: this is deprecated 405 - name: artifactUrl 406 type: string 407 description: 408 "Path/URL pointing to an additional artifact repository for resolution of additional 409 artifacts during the build" 410 scope: 411 - PARAMETERS 412 - STAGES 413 - STEPS 414 - name: considerSuspicious 415 type: bool 416 description: "Whether suspicious issues should trigger the check to fail or not" 417 scope: 418 - PARAMETERS 419 - STAGES 420 - STEPS 421 default: true 422 - name: convertToSarif 423 type: bool 424 description: "[BETA] Convert the proprietary format of Fortify scan results to the open SARIF standard. Uploaded through Cumulus later on." 425 scope: 426 - PARAMETERS 427 - STAGES 428 - STEPS 429 default: false 430 - name: fprUploadEndpoint 431 aliases: 432 - name: fortifyFprUploadEndpoint 433 type: string 434 description: "Fortify SSC endpoint for FPR uploads" 435 scope: 436 - GENERAL 437 - PARAMETERS 438 - STAGES 439 - STEPS 440 default: "/upload/resultFileUpload.html" 441 - name: projectName 442 aliases: 443 - name: fortifyProjectName 444 type: string 445 description: "The project used for reporting results in SSC" 446 scope: 447 - PARAMETERS 448 - STAGES 449 - STEPS 450 default: '{{list .GroupID .ArtifactID | join "-" | trimAll "-"}}' 451 - name: reporting 452 type: bool 453 description: Influences whether a report is generated or not 454 scope: 455 - PARAMETERS 456 - STAGES 457 - STEPS 458 default: false 459 - name: serverUrl 460 aliases: 461 - name: fortifyServerUrl 462 - name: sscUrl 463 deprecated: true 464 type: string 465 description: "Fortify SSC Url to be used for accessing the APIs" 466 mandatory: true 467 scope: 468 - GENERAL 469 - PARAMETERS 470 - STAGES 471 - STEPS 472 - name: pullRequestMessageRegexGroup 473 type: int 474 description: "The group number for extracting the pull request id in `'pullRequestMessageRegex'`" 475 scope: 476 - PARAMETERS 477 - STAGES 478 - STEPS 479 default: 1 480 - name: deltaMinutes 481 type: int 482 description: 483 "The number of minutes for which an uploaded FPR artifact is considered to be recent and 484 healthy, if exceeded an error will be thrown" 485 scope: 486 - PARAMETERS 487 - STAGES 488 - STEPS 489 default: 5 490 - name: spotCheckMinimum 491 type: int 492 description: 493 "The minimum number of issues that must be audited per category in the `Spot Checks of each 494 Category` folder to avoid an error being thrown" 495 scope: 496 - PARAMETERS 497 - STAGES 498 - STEPS 499 default: 1 500 - name: fprDownloadEndpoint 501 aliases: 502 - name: fortifyFprDownloadEndpoint 503 type: string 504 description: "Fortify SSC endpoint for FPR downloads" 505 scope: 506 - GENERAL 507 - PARAMETERS 508 - STAGES 509 - STEPS 510 default: "/download/currentStateFprDownload.html" 511 - name: versioningModel 512 aliases: 513 - name: defaultVersioningModel 514 deprecated: true 515 type: string 516 description: 517 "The default project versioning model used for creating the version based on the build descriptor version to report results in SSC, can be one of `'major'`, 518 `'major-minor'`, `'semantic'`, `'full'`" 519 scope: 520 - PARAMETERS 521 - GENERAL 522 - STAGES 523 - STEPS 524 default: "major" 525 possibleValues: 526 - major 527 - major-minor 528 - semantic 529 - full 530 - name: pythonInstallCommand 531 type: string 532 description: 533 "Additional install command that can be run when `buildTool: 'pip'` 534 is used which allows further customizing the execution environment of the scan" 535 scope: 536 - PARAMETERS 537 - STAGES 538 - STEPS 539 default: "{{.Pip}} install --user ." 540 - name: reportTemplateId 541 type: int 542 description: "Report template ID to be used for generating the Fortify report" 543 scope: 544 - PARAMETERS 545 - STAGES 546 - STEPS 547 default: 18 548 - name: filterSetTitle 549 type: string 550 description: "Title of the filter set to use for analysing the results" 551 scope: 552 - PARAMETERS 553 - STAGES 554 - STEPS 555 default: "SAP" 556 - name: pullRequestName 557 type: string 558 description: 559 "The name of the pull request branch which will trigger creation of a new version in Fortify 560 SSC based on the master branch version" 561 scope: 562 - PARAMETERS 563 - STAGES 564 - STEPS 565 - name: pullRequestMessageRegex 566 type: string 567 description: "Regex used to identify the PR-XXX reference within the merge commit message" 568 scope: 569 - PARAMETERS 570 - STAGES 571 - STEPS 572 default: '.*Merge pull request #(\\d+) from.*' 573 - name: buildTool 574 type: string 575 description: "Scan type used for the step which can be `'maven'`, `'pip'` or `'gradle'`" 576 scope: 577 - GENERAL 578 - PARAMETERS 579 - STAGES 580 - STEPS 581 default: maven 582 # Global maven settings, should be added to all maven steps 583 - name: projectSettingsFile 584 type: string 585 description: Path to the mvn settings file that should be used as project settings file. 586 scope: 587 - GENERAL 588 - STEPS 589 - STAGES 590 - PARAMETERS 591 aliases: 592 - name: maven/projectSettingsFile 593 - name: globalSettingsFile 594 type: string 595 description: Path to the mvn settings file that should be used as global settings file. 596 scope: 597 - GENERAL 598 - STEPS 599 - STAGES 600 - PARAMETERS 601 aliases: 602 - name: maven/globalSettingsFile 603 - name: m2Path 604 type: string 605 description: Path to the location of the local repository that should be used. 606 scope: 607 - GENERAL 608 - STEPS 609 - STAGES 610 - PARAMETERS 611 aliases: 612 - name: maven/m2Path 613 - name: verifyOnly 614 type: bool 615 description: Whether the step shall only apply verification checks or whether it does a full scan and check cycle 616 scope: 617 - PARAMETERS 618 - STAGES 619 - STEPS 620 default: false 621 - name: installArtifacts 622 type: bool 623 description: 624 "If enabled, it will install all artifacts to the local maven repository to make them available before running Fortify. 625 This is required if any maven module has dependencies to other modules in the repository and they were not installed before." 626 scope: 627 - GENERAL 628 - STEPS 629 - STAGES 630 - PARAMETERS 631 - name: createResultIssue 632 type: bool 633 description: Activate creation of a result issue in GitHub. 634 longDescription: | 635 Whether the step creates a GitHub issue containing the scan results in the originating repo. 636 Since optimized pipelines are headless the creation is implicitly activated for scheduled runs. 637 resourceRef: 638 - name: commonPipelineEnvironment 639 param: custom/isOptimizedAndScheduled 640 scope: 641 - GENERAL 642 - PARAMETERS 643 - STAGES 644 - STEPS 645 default: false 646 containers: 647 - image: "" 648 outputs: 649 resources: 650 - name: influx 651 type: influx 652 params: 653 - name: step_data 654 fields: 655 - name: fortify 656 type: bool 657 - name: fortify_data 658 fields: 659 - name: projectID 660 type: int64 661 - name: projectName 662 - name: projectVersion 663 - name: projectVersionId 664 type: int64 665 - name: violations 666 type: int 667 - name: corporateTotal 668 type: int 669 - name: corporateAudited 670 type: int 671 - name: auditAllTotal 672 type: int 673 - name: auditAllAudited 674 type: int 675 - name: spotChecksTotal 676 type: int 677 - name: spotChecksAudited 678 type: int 679 - name: spotChecksGap 680 type: int 681 - name: suspicious 682 type: int 683 - name: exploitable 684 type: int 685 - name: suppressed 686 type: int 687 - name: reports 688 type: reports 689 params: 690 - filePattern: "**/*.PDF" 691 type: fortify 692 - filePattern: "**/*.fpr" 693 type: fortify 694 - filePattern: "**/fortify-scan.*" 695 type: fortify 696 - filePattern: "**/toolrun_fortify_*.json" 697 type: fortify 698 - filePattern: "**/piper_fortify_report.json" 699 type: fortify 700 - filePattern: "**/piper_fortify_report.html" 701 type: fortify