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