GraphQL

"""
Repository is a source repository
"""
type Repository {
  """
  what platform hosts the source code that this repository is for? i.e. `github`, `gitlab`, `gitea`, etc
  """
  platform: String!
  """
  what organisation manages the source code that this repository is for? Can include `/` for nested organisations
  """
  organisation: String!
  """
  what is the repo name?
  """
  repo: String!

  """
  owner contains information about the owner of a given repository
  """
  owner: Owner

  """
  totalDependencies is the total number of dependencies that this Repository contains
  """
  totalDependencies: Int!
  """
  dependencies are the dependencies that this Repository contains
  """
  dependencies: [Dependency!]

  """
  totalAdvisories is the total number of Advisories (https://dmd.tanna.dev/concepts/advisory/) flagged against the dependencies this Repository contains, for instance to indicate lack of maintainence upstream, security issues, etc

  NOTE: This will include `totalPolicyViolations`

  TODO: https://gitlab.com/tanna.dev/dependency-management-data/-/issues/400
  """
  totalAdvisories: Int!
  """
  advisories are the Advisories (https://dmd.tanna.dev/concepts/advisory/) flagged against the dependencies this Repository contains, for instance to indicate lack of maintainence upstream, security issues, etc. Will include the results of `policyViolations`

  NOTE: This will includes the results of `policyViolations`

  TODO: https://gitlab.com/tanna.dev/dependency-management-data/-/issues/400
  """
  advisories: [Advisory!]

  """
  totalPolicyViolations are the number of `PolicyViolation`s that have been flagged against this Repository, based on configured policies

  NOTE: This does not include all values of `advisories`, only those that have an `AdvisoryType == POLICY`

  TODO: https://gitlab.com/tanna.dev/dependency-management-data/-/issues/400
  """
  totalPolicyViolations: Int!
  """
  policyViolations are the `PolicyViolation`s that have been flagged against this Repository, based on configured policies

  NOTE: This does not include all values of `advisories`, only those that have an `AdvisoryType == POLICY`

  TODO: https://gitlab.com/tanna.dev/dependency-management-data/-/issues/400
  """
  policyViolations: [PolicyViolation!]
  """
libyear is the value of the Libyear metric, which is defined as "how many years between the version we're currently using and the latest version released", and then totalled across all libraries used by the project.

Dependencies with a Libyear value of 0 could indicate that either all dependencies are up-to-date, or that the Libyear could not be calculated and are not shown.

Note that a low number could still be problematic, for instance if a package has pushed out a dozen releases in the last month, all of which include significant breaking changes.

Alternatively, a package may have a low score simply because the package is no longer maintained, so no new releases means you are "up to date".

It is worth using this metric with context where possible, or at least with the above caveats in mind.

It is recommended to display this at a precision of 2 decimal places.

Further reading:

- https://chaoss.community/kb/metric-libyears/
- https://libyear.com/
  """
  libyears: Float!

  """
  metadata provides additional metadata about the underlying repository
  """
  metadata: RepositoryMetadata
}

type RepositoryMetadata {
  """
  isMonorepo indicates whether the repository is treated as a monorepo
  """
  isMonorepo: Boolean!
  """
  isFork indicates whether this is a forked repository. This could indicate that this is a temporary repository, a long-standing fork for security + supply-chain hygiene purposes, or some other reason.
  """
  isFork: Boolean!
  """
  repositoryType is a free-form field to create enum-style data, for instance `LIBRARY` or `SERVICE`, or `EXAMPLE_CODE`.

  This may track with your Developer Portal's own definition of a repository's type.
  """
  repositoryType: String!
  """
  repositoryUsage is a free-form field to note additional information
  around the repository's usage, which is organisation-specific.

  For instance, this may be enum-style data, a space-separated list of
  enum-style data, or a long human-readable description.
  """
  repositoryUsage: String
  """
  visibility indicates the repository's visibility in the source forge
  """
  visibility: RepositoryVisibility!
  """
  description is a textual description of the repo for more context, which can include links out to other systems i.e. a Service Catalog. The contents will be shown verbatim to a user, and will not be interpreted as markup
  """
  description: String
  """
  additionalMetadata contains additional key-value data that can be used to provide custom organisation-specific configuration, and augment any queries for data with information around this additional metadata.
  """
  addititionalMetadata: [RepositoryAdditionalMetadatum!]!
}

"""
additionalMetadata contains additional key-value data that can be used to provide custom organisation-specific configuration, and augment any queries for data with information around this additional metadata.

For instance:

- `last_commit_date` - the last commit date to the project
- `pci_environment` - the PCI environment the application is deployed to
- `customer_type` - i.e. whether it's used for government, financial
  users, etc
"""
type RepositoryAdditionalMetadatum {
  key: String!
  value: String!
}

"""
RepositoryVisibility indicates the repository's visibility in the source forge.

NOTE that this may be straightforward if you're using a publicly hosted source forge, but if you're running on an internally run, i.e. VPN'd off source force, this field may have a slightly different interpretation
"""
enum RepositoryVisibility {
  PUBLIC
  PRIVATE
  INTERNAL
}

"""
Owner models the definition of which team / person / vendor / part of your organisation / etc owns a given repository. This data is expected to be sourced through a Service Catalog or through some other means, and will be organisation-specific.
"""
type Owner {
  """
  owner is a free-form identifier for who owns the repository. This could be an email address, a team name, Slack channel name, etc, but should ideally be clear from this column who should be contacted about any queries about the repository
  """
  owner: String

  """
  notes allows adding additional, optional, context around the ownership, for instance a link to a Slack channel, Confluence page, internal Service Catalog, etc. The contents will be shown verbatim to a user, and will not be interpreted as markup.
  """
  notes: String
}

"""
Dependency models a given package dependency
"""
type Dependency {
  """
  packageName contains the name of the package
  """
  packageName: String!
  """
  version indicates the version of this dependency

  NOTE this could be a version constraint, such as any of:

      <=1.3.4,>=1.3.0
      "~> 0.9"
      latest
      ^2.0.6
      =1.0.4

  As well as a specific value, such as:

      1.0.4
      10
      latest

  This versioning will be implementation-specific for the `packageManager` in use
  """
  version: String!
  """
  currentVersion defines the current version that this package's `version` resolves to

  If the `version` is an exact version number, such as `1.0.4`, then `currentVersion` will usually be the same value, `1.0.4`

  If the `version` is a version constraint, then this column MAY indicate the exact version that was resolved at the time of dependency analysis
  """
  currentVersion: String
  """
  packageManager indicates the package manager that the dependency is from
  """
  packageManager: String!
  """
  packageFilePath defines the path within `repo` that defines the `packageName` as a dependency. For example:

      .github/workflows/build.yml
      go.mod
      build/Dockerfile

  NOTE that this may be empty (https://gitlab.com/tanna.dev/dependency-management-data/-/issues/396)
  """
  packageFilePath: String
  """
  depTypes defines the different dependency types that may be in use. This will always be a JSON array, with 0 or more string elements. For example:

      []
      ["action"]
      ["dependencies","lockfile"]
      ["dependencies","missing-data"]
      ["lockfile","lockfile-yarn-pinning-^21.1.1"]
      ["engines"]

  Based on which datasource(s) (https://dmd.tanna.dev/concepts/datasource/) you are using, this will have different values and meanings

  NOTE that in the future these there will be a more consistent naming structure for these (https://gitlab.com/tanna.dev/dependency-management-data/-/issues/379)
  """
  depTypes: [String!]

  """
  health defines metrics that can be used to determine how healthy the dependency is.
  """
  health: DependencyHealth
}

"""
DependencyHealth contains information about the health of given dependencies.

This consumes data from different sources to augment the understanding of dependencies in use, for instance giving an indication of whether they are (well) maintained, have been recently released, or may have supply chain hygiene issues.

Currently, this data is derived from:

- OpenSSF Security Scorecards (https://api.securityscorecards.dev/)
- Ecosystems (https://ecosyste.ms)

This data is a best-efforts attempt to provide this insight, and may be stale at the time of querying.
"""
type DependencyHealth {
  """
  securityScorecard contains metadata from OpenSSF Security Scorecards, and can indicate concerns for supply chain security hygiene.
  """
  securityScorecard: SecurityScorecard

  """
  ecosystems contains metadata from Ecosystems, and can indicate concerns around the package and its maintainence.
  """
  ecosystems: EcosystemsPackage
}

"""
SecurityScorecard contains metadata from OpenSSF Security Scorecards, and can indicate concerns for supply chain security hygiene.
"""
type SecurityScorecard {
  """
  score is the overall calculated value of the OpenSSF Security Scorecards' checks for the given dependency.
  """
  score: Float
  """
  codeReview is the value of the OpenSSF Security Scorecards' `Code-Review` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#code-review
  """
  codeReview: Int
  """
  scorecard_maintained is the value of the OpenSSF Security Scorecards' `Maintained` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
  """
  maintained: Int
  """
  ciiBestPractices is the value of the OpenSSF Security Scorecards' `CII-Best-Practices` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#cii-best-practices
  """
  ciiBestPractices: Int
  """
  license is the value of the OpenSSF Security Scorecards' `License` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#license
  """
  license: Int
  """
  dangerousWorkflow is the value of the OpenSSF Security Scorecards' `Dangerous-Workflow` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow
  """
  dangerousWorkflow: Int
  """
  packaging is the value of the OpenSSF Security Scorecards' `Packaging` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging
  """
  packaging: Int
  """
  tokenPermissions is the value of the OpenSSF Security Scorecards' `Token-Permissions` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions
  """
  tokenPermissions: Int
  """
  signedReleases is the value of the OpenSSF Security Scorecards' `Signed-Releases` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#signed-releases
  """
  signedReleases: Int
  """
  branchProtection is the value of the OpenSSF Security Scorecards' `Branch-Protection` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
  """
  branchProtection: Int
  """
  binaryArtifacts is the value of the OpenSSF Security Scorecards' `Binary-Artifacts` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#binary-artifacts
  """
  binaryArtifacts: Int
  """
  fuzzing is the value of the OpenSSF Security Scorecards' `Fuzzing` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#fuzzing
  """
  fuzzing: Int
  """
  securitypolicy is the value of the OpenSSF Security Scorecards' `Security-Policy` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#security-policy
  """
  securityPolicy: Int
  """
  sast is the value of the OpenSSF Security Scorecards' `SAST` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#sast
  """
  sast: Int
  """
  vulnerabilities is the value of the OpenSSF Security Scorecards' `Vulnerabilities` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities
  """
  vulnerabilities: Int
  """
  pinnedDependencies is the value of the OpenSSF Security Scorecards' `Pinned-Dependencies` check.

  More details on the calculation can be found at https://github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies
  """
  pinnedDependencies: Int
}

"""
EcosystemsPackage defines Ecosyte.ms' understanding of a given package
"""
type EcosystemsPackage {
  """
  repo contains repository-specific metadata
  """
  repo: EcosystemsRepo

  """
  latestReleasePublishedAt contains the date the last release was made, if any
  """
  latestReleasePublishedAt: String
  """
  lastSyncedAt indicates the last date that Ecosystems synced package data.

  This is useful when used in conjunction with decisioning based on other fields, as it indicates how stale the data may be.
  """
  lastSyncedAt: String
  """
  status indicates the status of the package.

  Some possible values:

    yanked
    deprecated
    discontinued
  """
  status: String

  """
  funding defines the different platform(s) that the dependency is seeking financial support on.
  """
  funding: [FundingPlatform!]
}

"""
FundingPlatform defines information around the different platform(s) that the dependency is seeking financial support on.
"""
type FundingPlatform {
  key: String!
  value: String!
}

"""
EcosystemsRepo defines Ecosyte.ms' understanding of a given source code repository
"""
type EcosystemsRepo {
  """
  archived indicates whether the repository has been archived (made read-only)
  """
  archived: Boolean
  """
  pushedAt indicates the last push to the default branch of -- the source code repository that manages this package.
  """
  pushedAt: String
  """
  ecosystems_repo_updated_at indicates the last activity in the source code repository that manages this package.

  Depending on the host of the source code, this could indicate a comments, push to a branch, or otherwise.
  """
  updatedAt: String
  """
  lastSyncedAt indicates the last date that Ecosystems synced repository data.

  This is useful when used in conjunction with decisioning based on other fields, as it indicates how stale the data may be.
  """
  lastSyncedAt: String
}

"""
AdvisoryType defines the type of Advisory (https://dmd.tanna.dev/concepts/advisory/) that this will flagged as
"""
enum AdvisoryType {
  """
  The dependency is deprecated, and should ideally be replaced
  """
  DEPRECATED
  """
  The dependency is no longer maintained
  """
  UNMAINTAINED
  """
  There is a security issue with this dependency
  """
  SECURITY
  """
  There is organisational policy that recommends awareness of the use of this
  dependency
  """
  POLICY
  """
  There is no other `AdvisoryType` that makes sense for this type. If you feel there should be, please raise an issue on the issue tracker (https://gitlab.com/tanna.dev/dependency-management-data/-/issues)
  """
  OTHER
}

"""
PolicyViolationLevel defines the severity of the Policy Violation. This will be organisation-specific in terms of what you deem most critical, but an example of what this could look like is:

  ERROR: "Use of AGPL-3.0 licensed dependencies anywhere is a high-severity"
  WARN:  "Using a dependency that hasn't been updated in 1 year should be avoided"
"""
enum PolicyViolationLevel {
  ERROR
  WARN
}

"""
PolicyViolation is a violation of organisational policy (https://dmd.tanna.dev/concepts/policy/)
"""
type PolicyViolation {
  """
  dependency is the underlying dependency that this Policy Violation is flagged against
  """
  dependency: Dependency!
  """
  level defines the severity of the Policy Violation. This will be organisation-specific in terms of what you deem most critical, but an example of what this could look like is:
  """
  level: PolicyViolationLevel!
  """
  advisoryType defines the type of Advisory (https://dmd.tanna.dev/concepts/advisory/) that this Policy Violation will flagged as
  """
  advisoryType: AdvisoryType!
  """
  description is a human-readable explanation of why this advisory is being flagged. The contents will be shown verbatim to a user, and will not be interpreted as markup

  This can be as long and detailed as you wish, and is recommended to include links to (internal) documentation around the finding, any known remediation actions, and communication channels to reach out to for information
  """
  description: String!
}

"""
Advisory (https://dmd.tanna.dev/concepts/advisory/) is an indication of issues flagged against the dependencies this Repository contains, for instance to indicate lack of maintainence upstream, security issues, etc
"""
type Advisory {
  """
  dependency is the underlying dependency that this Advisory is flagged against
  """
  dependency: Dependency!
  """
  advisoryType defines the type of Advisory (https://dmd.tanna.dev/concepts/advisory/) that this Advisory will flagged as
  """
  advisoryType: AdvisoryType!
  """
  description is a human-readable explanation of why this advisory is being flagged. The contents will be shown verbatim to a user, and will not be interpreted as markup

  This can be as long and detailed as you wish, and is recommended to include links to (internal) documentation around the finding, any known remediation actions, and communication channels to reach out to for information
  """
  description: String!
  """
  supportedUntil describes the date that this release will be marked as End of Life, and will no longer be maintained from
  """
  supportedUntil: String
  """
  endOfLifeFrom describes the date that this release will be marked as End of Life, and will no longer be maintained from
  """
  endOfLifeFrom: String
}

"""
Metadata tracks information about metadata of the dependency-management-data installation
"""
type Metadata {
  """
  DMDVersion is the version of the `dmd` CLI that was used to create the underlying database
  """
  DMDVersion: String!
  """
  finalisedAt is the date at which the database was "finalised", and should now be treated as "up-to-date" and read-only from this point onwards.

  This indicates that all datasources were imported and all enrichment (i.e. via Advisories, Dependency Health, etc) was complete.

  This could indicate that all datasources' data is now up-to-date, but there are likely some that haven't been as recently scanned.
  """
  finalisedAt: String
}

type RepositoriesResponse {
  repositories: [Repository!]

  totalAdvisories: Int!
  totalDependencies: Int!
  totalPolicyViolations: Int!
}

type DependentOnResponse {
  repositories: [DependentOnUsage!]
}

type DependentOnUsage {
  platform: String!
  organisation: String!
  repo: String!
  version: String
  currentVersion: String
  depTypes: [String!]
  packageFilePath: String
  owner: Owner
}

input RepositoryKey {
  platform: String!
  organisation: String!
  repo: String!
}

type Query {
  """
  getMetadata retrieves information about metadata of the dependency-management-data installation
  """
  getMetadata: Metadata!

  """
  dependentOn reports usage of a given dependency, and optionally the specific version in use, across all known projects in the database

  This provides a view of the impact of the usage of a given dependency for instance when understanding an unmaintained/end-of-life dependency, security issues, or simply understanding the uptake of a given dependency

  The `currentVersion` is prioritised over `version`
  """
  dependentOn(
    """
    packageName contains the name of the package
    """
    packageName: String!,
    """
    version indicates the version of this dependency

    NOTE this could be a version constraint, such as any of:

        <=1.3.4,>=1.3.0
        "~> 0.9"
        latest
        ^2.0.6
        =1.0.4

    As well as a specific value, such as:

        1.0.4
        10
        latest

    This versioning will be implementation-specific for the `packageManager` in use
    """
    version: String,
    """
    currentVersion defines the current version that this package's `version` resolves to

    If the `version` is an exact version number, such as `1.0.4`, then `currentVersion` will usually be the same value, `1.0.4`

    If the `version` is a version constraint, then this column MAY indicate the exact version that was resolved at the time of dependency analysis
    """
    currentVersion: String,
    """
    packageManager indicates the package manager the given dependency is managed by

    Based on which datasource(s) (https://dmd.tanna.dev/concepts/datasource/) you are using, this will have different values and meanings
    """
    packageManager: String!): DependentOnResponse!

  """
  repository queries a given repository's data
  """
  repository(key: RepositoryKey): Repository!

  """
  repositoriesLike queries multiple repositories' data, based on wildcarded platform/organisation/repos
  """
  repositoriesLike(
    """
    platformLike is a wildcard-like platform for the source code that this repository is for

    This can include a `*` character to indicate a wildcard such as:

        git*b
        *bucket
    """
    platformLike: String,
    """
    organisationLike is a wildcard-like organisation which manages this repo. Can include `/` for nested organisations

    This can include a `*` character to indicate a wildcard such as:

        */oapi-codegen
        *
        *tanna*
        *tan*na*
    """
    organisationLike: String,
    """
    repoLike is a wildcard-like repo

    This can include a `*` character to indicate a wildcard such as:

        *openapi*
        *
    """
    repoLike: String): RepositoriesResponse!

  """
  repositoriesLike queries multiple repositories' data, based on a provided list of `RepositoryKey`s
  """
  repositoriesIn(keys: [RepositoryKey!]!): RepositoriesResponse!
}