harborapi.models.scanner
DEFAULT_VENDORS = ('nvd', 'redhat')
module-attribute
SEVERITY_PRIORITY: Final[Dict[Severity, int]] = {Severity.none: 0, Severity.unknown: 1, Severity.negligible: 2, Severity.low: 3, Severity.medium: 4, Severity.high: 5, Severity.critical: 6}
module-attribute
Scanner
Bases: BaseModel
Basic scanner properties such as name, vendor, and version.
Source code in harborapi/models/scanner.py
name: Optional[str] = Field(default=None, description='The name of the scanner.', examples=['Trivy'])
class-attribute
instance-attribute
vendor: Optional[str] = Field(default=None, description="The name of the scanner's provider.", examples=['Aqua Security'])
class-attribute
instance-attribute
version: Optional[str] = Field(default=None, description='The version of the scanner.', examples=['0.4.0'])
class-attribute
instance-attribute
semver: SemVer
property
ScannerProperties
Bases: StrDictRootModel[str]
A set of custom properties that can further describe capabilities of a given scanner.
Source code in harborapi/models/scanner.py
root: Optional[Dict[str, str]] = None
class-attribute
instance-attribute
ScannerCapability
Bases: BaseModel
Capability consists of the set of recognized artifact MIME types and the set of scanner report MIME types.
For example, a scanner capable of analyzing Docker images and producing a vulnerabilities report recognizable
by Harbor web console might be represented with the following capability:
- consumes MIME types:
- application/vnd.oci.image.manifest.v1+json
- application/vnd.docker.distribution.manifest.v2+json
- produces MIME types:
- application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0
Source code in harborapi/models/scanner.py
consumes_mime_types: List[str] = Field(..., description='The set of MIME types of the artifacts supported by the scanner to produce the reports specified in the "produces_mime_types". A given\nmime type should only be present in one capability item.\n', examples=[['application/vnd.oci.image.manifest.v1+json', 'application/vnd.docker.distribution.manifest.v2+json']])
class-attribute
instance-attribute
produces_mime_types: List[str] = Field(..., description='The set of MIME types of reports generated by the scanner for the consumes_mime_types of the same capability record.\n', examples=[['application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0']])
class-attribute
instance-attribute
ScanRequestId
Bases: StrRootModel
Source code in harborapi/models/scanner.py
root: str = Field(..., description='A unique identifier returned by the [/scan](#/operation/AcceptScanRequest] operations. The format of the\nidentifier is not imposed but it should be unique enough to prevent collisons when polling for scan reports.\n', examples=['3fa85f64-5717-4562-b3fc-2c963f66afa6'])
class-attribute
instance-attribute
Registry
Bases: BaseModel
Source code in harborapi/models/scanner.py
url: Optional[str] = Field(default=None, description='A base URL or the Docker Registry v2 API.', examples=['https://core.harbor.domain'])
class-attribute
instance-attribute
authorization: Optional[str] = Field(default=None, description="An optional value of the HTTP Authorization header sent with each request to the Docker Registry v2 API.\nIt's used to exchange Base64 encoded robot account credentials to a short lived JWT access token which\nallows the underlying scanner to pull the artifact from the Docker Registry.\n", examples=['Basic BASE64_ENCODED_CREDENTIALS'])
class-attribute
instance-attribute
Artifact
Bases: BaseModel
Source code in harborapi/models/scanner.py
repository: Optional[str] = Field(default=None, description='The name of the Docker Registry repository containing the artifact.', examples=['library/mongo'])
class-attribute
instance-attribute
digest: Optional[str] = Field(default=None, description="The artifact's digest, consisting of an algorithm and hex portion.", examples=['sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b'])
class-attribute
instance-attribute
tag: Optional[str] = Field(default=None, description="The artifact's tag", examples=['3.14-xenial'])
class-attribute
instance-attribute
mime_type: Optional[str] = Field(default=None, description='The MIME type of the artifact.', examples=['application/vnd.docker.distribution.manifest.v2+json'])
class-attribute
instance-attribute
Severity
Bases: Enum
A standard scale for measuring the severity of a vulnerability.
Unknown
- either a security problem that has not been assigned to a priority yet or a priority that the scanner did not recognize.Negligible
- technically a security problem, but is only theoretical in nature, requires a very special situation, has almost no install base, or does no real damage.Low
- a security problem, but is hard to exploit due to environment, requires a user-assisted attack, a small install base, or does very little damage.Medium
- a real security problem, and is exploitable for many people. Includes network daemon denial of service attacks, cross-site scripting, and gaining user privileges.High
- a real problem, exploitable for many people in a default installation. Includes serious remote denial of service, local root privilege escalations, or data loss.Critical
- a world-burning problem, exploitable for nearly all people in a default installation. Includes remote root privilege escalations, or massive data loss.
Source code in harborapi/models/scanner.py
unknown = 'Unknown'
class-attribute
instance-attribute
negligible = 'Negligible'
class-attribute
instance-attribute
low = 'Low'
class-attribute
instance-attribute
medium = 'Medium'
class-attribute
instance-attribute
high = 'High'
class-attribute
instance-attribute
critical = 'Critical'
class-attribute
instance-attribute
none = 'None'
class-attribute
instance-attribute
__gt__(other)
__ge__(other)
__lt__(other)
Error
CVSSDetails
Bases: BaseModel
Source code in harborapi/models/scanner.py
score_v3: Optional[float] = Field(default=None, description='The CVSS 3.0 score for the vulnerability.\n', examples=[3.2])
class-attribute
instance-attribute
score_v2: Optional[float] = Field(default=None, description='The CVSS 2.0 score for the vulnerability.\n')
class-attribute
instance-attribute
vector_v3: Optional[str] = Field(default=None, description='The CVSS 3.0 vector for the vulnerability. \n', examples=['CVSS:3.0/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N'])
class-attribute
instance-attribute
vector_v2: Optional[str] = Field(default=None, description='The CVSS 2.0 vector for the vulnerability. The string is of the form AV:L/AC:M/Au:N/C:P/I:N/A:N\n', examples=['AV:N/AC:L/Au:N/C:N/I:N/A:P'])
class-attribute
instance-attribute
ScannerAdapterMetadata
Bases: BaseModel
Represents metadata of a Scanner Adapter which allows Harbor to lookup a scanner capable of scanning a given Artifact stored in its registry and making sure that it can interpret a returned result.
Source code in harborapi/models/scanner.py
scanner: Scanner
instance-attribute
capabilities: List[ScannerCapability]
instance-attribute
properties: Optional[ScannerProperties] = None
class-attribute
instance-attribute
ScanRequest
ScanResponse
VulnerabilityItem
Bases: BaseModel
Source code in harborapi/models/scanner.py
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 |
|
id: Optional[str] = Field(default=None, description='The unique identifier of the vulnerability.', examples=['CVE-2017-8283'])
class-attribute
instance-attribute
package: Optional[str] = Field(default=None, description='An operating system package containing the vulnerability.\n', examples=['dpkg'])
class-attribute
instance-attribute
version: Optional[str] = Field(default=None, description='The version of the package containing the vulnerability.\n', examples=['1.17.27'])
class-attribute
instance-attribute
fix_version: Optional[str] = Field(default=None, description='The version of the package containing the fix if available.\n', examples=['1.18.0'])
class-attribute
instance-attribute
severity: Severity = Field(Severity.unknown, description='The severity of the vulnerability.')
class-attribute
instance-attribute
description: Optional[str] = Field(default=None, description='The detailed description of the vulnerability.\n', examples=['dpkg-source in dpkg 1.3.0 through 1.18.23 is able to use a non-GNU patch program\nand does not offer a protection mechanism for blank-indented diff hunks, which\nallows remote attackers to conduct directory traversal attacks via a crafted\nDebian source package, as demonstrated by using of dpkg-source on NetBSD.\n'])
class-attribute
instance-attribute
links: Optional[List[str]] = Field(None, description='The list of links to the upstream databases with the full description of the vulnerability.\n')
class-attribute
instance-attribute
preferred_cvss: Optional[CVSSDetails] = None
class-attribute
instance-attribute
cwe_ids: Optional[List[str]] = Field(default=None, description='The Common Weakness Enumeration Identifiers associated with this vulnerability.\n', examples=[['CWE-476']])
class-attribute
instance-attribute
vendor_attributes: Optional[Dict[str, Any]] = None
class-attribute
instance-attribute
semver: SemVer
property
fixable: bool
property
get_cvss_score(scanner='Trivy', version=3, vendor_priority=None, default=0.0)
The default scanner Trivy, as of version 0.29.1, does not use the preferred_cvss field.
In order to not tightly couple this method with a specific scanner, we use the scanner name to determine how to retrieve the CVSS score.
Forward compatibility is in place in the event that Trivy starts conforming to the spec.
Source code in harborapi/models/scanner.py
get_severity(scanner='Trivy', vendor_priority=None)
Returns the CVSS V3 severity of the vulnerability based on a specific vendor. If no vendor is specified, the default vendor priority is used (NVD over RedHat).
With Trivy 0.29.1, the severity
field is based on the Red Hat vulnerability rating.
This attempts to return the severity based on a user-provided vendor priority.
TODO: improve documentation for the what and why of this method
Source code in harborapi/models/scanner.py
get_severity_highest(scanner='Trivy', vendors=None)
Attempts to find the highest severity of the vulnerability based on a specific vendor.
Source code in harborapi/models/scanner.py
ErrorResponse
HarborVulnerabilityReport
Bases: BaseModel
Source code in harborapi/models/scanner.py
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 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 |
|
generated_at: Optional[AwareDatetime] = Field(None, description='The time the vulnerability report was generated.')
class-attribute
instance-attribute
artifact: Optional[Artifact] = Field(default=None, description='The scanned artifact.')
class-attribute
instance-attribute
scanner: Optional[Scanner] = Field(default=None, description='The scanner used to generate the report.')
class-attribute
instance-attribute
severity: Optional[Severity] = Field(default=Severity.unknown, description='The overall severity of the vulnerabilities.')
class-attribute
instance-attribute
vulnerabilities: List[VulnerabilityItem] = Field(default_factory=list, description='The list of vulnerabilities found.')
class-attribute
instance-attribute
model_config = ConfigDict(ignored_types=(cached_property))
class-attribute
instance-attribute
fixable: List[VulnerabilityItem]
property
unfixable: List[VulnerabilityItem]
property
critical: List[VulnerabilityItem]
property
high: List[VulnerabilityItem]
property
medium: List[VulnerabilityItem]
property
low: List[VulnerabilityItem]
property
distribution: Counter[Severity]
property
cvss_scores: List[float]
cached
property
__repr__()
vulnerabilities_by_severity(severity)
sort(descending=True, use_cvss=False)
Sorts the vulnerabilities by severity in place.
A wrapper around vulnerabilities.sort
that sorts by severity,
then optionally by CVSS score to break ties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
descending |
bool
|
Whether to sort in descending order, by default True
Equivalent to |
True
|
use_cvss |
bool
|
Whether to use CVSS score to determine sorting order when items have identical severity, by default False This is somewhat experimental and may be removed in the future. |
False
|
Source code in harborapi/models/scanner.py
top_vulns(n=5, fixable=False)
Returns the n most severe vulnerabilities.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
n |
int
|
The maximum number of vulnerabilities to return. |
5
|
fixable |
bool
|
If |
False
|
Returns:
Type | Description |
---|---|
List[VulnerabilityItem]
|
The n most severe vulnerabilities. |
Source code in harborapi/models/scanner.py
has_cve(cve_id, case_sensitive=False)
Whether or not the report contains a vulnerability with the given CVE ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cve_id |
str
|
The CVE ID to search for. |
required |
Returns:
Type | Description |
---|---|
bool
|
Report contains the a vulnerability with the given CVE ID. |
Source code in harborapi/models/scanner.py
has_description(description, case_sensitive=False)
Whether or not the report contains a vulnerability whose description contains the given string.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
description |
str
|
The string to search for in the descriptions. |
required |
case_sensitive |
bool
|
Case sensitive search, by default False |
False
|
Returns:
Type | Description |
---|---|
bool
|
The report contains a vulnerability whose description contains the given string. |
Source code in harborapi/models/scanner.py
has_package(package, case_sensitive=False)
Whether or not the report contains a vulnerability affecting the given package.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
package |
str
|
Name of the package to search for. |
required |
case_sensitive |
bool
|
Case sensitive search, by default False |
False
|
Returns:
Type | Description |
---|---|
bool
|
The given package is affected by a vulnerability in the report. |
Source code in harborapi/models/scanner.py
vuln_with_cve(cve, case_sensitive=False)
Returns a vulnerability with the specified CVE ID if it exists in the report.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cve |
str
|
The CVE ID of the vulnerability to return. |
required |
case_sensitive |
bool
|
Case sensitive search, by default False |
False
|
Returns:
Type | Description |
---|---|
Optional[VulnerabilityItem]
|
A vulnerability with the specified CVE ID if it exists, otherwise |
Source code in harborapi/models/scanner.py
vulns_with_package(package, case_sensitive=False)
Generator that yields all vulnerabilities that affect the given package.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
package |
str
|
The package name to search for. |
required |
case_sensitive |
bool
|
Case sensitive search, by default False |
False
|
Yields:
Type | Description |
---|---|
VulnerabilityItem
|
Vulnerability that affects the given package. |
Source code in harborapi/models/scanner.py
vulns_with_description(description, case_sensitive=False)
Generator that yields all vulnerabilities whose description contains the given string.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
description |
str
|
The string to search for in vulnerability descriptions. |
required |
case_sensitive |
bool
|
Case sensitive search, by default False |
False
|
Yields:
Type | Description |
---|---|
VulnerabilityItem
|
Vulnerability whose description contains the given string. |
Source code in harborapi/models/scanner.py
most_severe(severities)
Returns the highest severity in a list of severities.
sort_distribution(distribution)
Turn a counter of Severities into a sorted list of (severity, count) tuples.