> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kosli.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.kosli.com/feedback

```json
{
  "path": "/client_reference/kosli_fingerprint",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# kosli fingerprint

> Calculate the SHA256 fingerprint of an artifact.

## Synopsis

```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli fingerprint {IMAGE-NAME | FILE-PATH | DIR-PATH} [flags]
```

Calculate the SHA256 fingerprint of an artifact.
Requires `--artifact-type` flag to be set.
Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container
images in registries or "docker" for local docker images.

Fingerprinting container images can be done using the local docker daemon or the fingerprint can be fetched
from a remote registry.

Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon, so
the image must have been pushed to or pulled from a registry. A freshly built image (just
`docker build`) does not have a repo digest. For images already in a registry, prefer
`--artifact-type=oci` to fetch the digest directly from the registry.

When fingerprinting a 'dir' artifact, you can exclude certain paths from fingerprint calculation
using the `--exclude` flag.
Excluded paths are relative to the DIR-PATH and can be literal paths or glob patterns.
With a directory structure like this `foo/bar/zam/file.txt` if you are calculating the fingerprint of `foo/bar` you need to
exclude `zam/file.txt` which is relative to the DIR-PATH.
The supported glob pattern syntax is what is documented here: [https://pkg.go.dev/path/filepath#Match](https://pkg.go.dev/path/filepath#Match) ,
plus the ability to use recursive globs "\*\*"

If the directory structure contains a symbolic link to a *file* (for example, a link 'from/this/file' and a target of 'to/another/file') then:

* the name of the link ('from/this/file') *is* included in the fingerprint.
* the name of the link ('from/this/file') *is* subject to `.kosli_ignore` entries.
* the name of the target ('to/another/file') is *not* included in the fingerprint.
* the content of target *is* included in the fingerprint, even if the target is outside the root directory being fingerprinted.

If the directory structure contains a symbolic link to a *directory* (for example, a link 'from/this/dir' and a target of 'to/another/dir') then:

* the name of the link ('from/this/dir') *is* included in the fingerprint.
* the name of the link ('from/this/dir') *is* subject to `.kosli_ignore` entries.
* the name of the target ('to/another/dir') *is* included in the fingerprint, even if the target is outside the root directory being fingerprinted.
* the name of the target ('to/another/dir') is *not* subject to `.kosli_ignore` entries.
* the content of the target is *not* included in the fingerprint.

To specify paths in a directory artifact that should always be excluded from the SHA256 calculation, you can add a `.kosli_ignore` file to the root of the artifact.
Each line should specify a relative path or path glob to be ignored. You can include comments in this file, using `#`.
The `.kosli_ignore` will be treated as part of the artifact like any other file, unless it is explicitly ignored itself.

## Flags

| Flag                       | Description                                                                                                                                                                                                                                    |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| -t, --artifact-type string | The type of the artifact to calculate its SHA256 fingerprint. One of: \[oci, docker, file, dir]. Only required if you want Kosli to calculate the fingerprint for you (i.e. when you don't specify '--fingerprint' on commands that allow it). |
| -x, --exclude strings      | \[optional] The comma separated list of directories and files to exclude from fingerprinting. Can take glob patterns. Only applicable for --artifact-type dir.                                                                                 |
| -h, --help                 | help for fingerprint                                                                                                                                                                                                                           |
| --registry-password string | \[conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry.                                                                              |
| --registry-username string | \[conditional] The container registry username. Only required if you want to read container image SHA256 digest from a remote container registry.                                                                                              |

## Flags inherited from parent commands

| Flag                      | Description                                                                                                 |
| :------------------------ | :---------------------------------------------------------------------------------------------------------- |
| -a, --api-token string    | The Kosli API token.                                                                                        |
| -c, --config-file string  | \[optional] The Kosli config file path. (default "kosli")                                                   |
| --debug                   | \[optional] Print debug logs to stdout. A boolean flag [docs](/faq/#boolean-flags) (default false)          |
| -H, --host string         | \[defaulted] The Kosli endpoint. (default "[https://app.kosli.com](https://app.kosli.com)")                 |
| --http-proxy string       | \[optional] The HTTP proxy URL including protocol and port number. e.g. `http://proxy-server-ip:proxy-port` |
| -r, --max-api-retries int | \[defaulted] How many times should API calls be retried when the API host is not reachable. (default 3)     |
| --org string              | The Kosli organization.                                                                                     |

## Live Examples in different CI systems

<Tabs>
  <Tab title="GitHub">
    View an example of the `kosli fingerprint` command in GitHub.

    In [this YAML file](https://github.com/cyber-dojo/snyk-scanning/blob/9508524934b5a7a42caedb42f6675d177f841568/.github/workflows/artifact_snyk_test.yml#L183)
  </Tab>
</Tabs>

## Examples Use Cases

These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](/getting_started/install/#assigning-flags-via-environment-variables).

<AccordionGroup>
  <Accordion title="fingerprint a file">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli fingerprint --artifact-type file file.txt

    ```
  </Accordion>

  <Accordion title="fingerprint a dir">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli fingerprint --artifact-type dir mydir

    ```
  </Accordion>

  <Accordion title="fingerprint a dir while excluding paths `mydir/logs` and `mydir/*.exe`">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli fingerprint --artifact-type dir --exclude logs --exclude *.exe mydir

    ```
  </Accordion>

  <Accordion title="fingerprint a dir while excluding all `.pyc` files">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli fingerprint --artifact-type dir  --exclude **/*.pyc mydir

    ```
  </Accordion>

  <Accordion title="fingerprint a dir while excluding paths in `.kosli_ignore` file">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    echo bar/file.txt > mydir/.kosli_ignore
    kosli fingerprint --artifact-type dir mydir

    ```
  </Accordion>

  <Accordion title="fingerprint a locally available docker image (requires docker daemon running)">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli fingerprint --artifact-type docker nginx:latest

    ```
  </Accordion>

  <Accordion title="fingerprint a public image from a remote registry">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli fingerprint --artifact-type oci nginx:latest

    ```
  </Accordion>

  <Accordion title="fingerprint a private image from a remote registry">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli fingerprint --artifact-type oci private:latest \
      --registry-username YourUsername \
      --registry-password YourPassword
    ```
  </Accordion>
</AccordionGroup>