verygood-ops / sftp-exporter

Prometheus metrics for SFTP servers and files.

sftp-exporter

Prometheus metrics exporter for SFTP.

How to run locally

python sftp-exporter.py <path_to_config>

path_to_config should be a path to a configuration YAML file at the same host.

By default, exporter listens on 127.0.0.1:9339.

Pass --host or --port parameters to change listen interface or port respectively.

How to run in docker

docker run -v <path_to_config>:/config.yml \
 -it quay.io/verygoodsecurity/sftp-exporter:dev-2.0.0

How to configure

Configuration file should contain list of SFTP check configurations under the single key checks

checks:
  - host: sftp1.my.org
    port: 4822
    ...
  - host: sftp2.my.org
    port: 4822

Available properties for SFTP check configuration:

• host A host where SFTP service is listening
• port Port of SFTP service (defaults to 22 if not passed)
• username Username to authenticate with (defaults to sftp)
• password Optional password to authenticate with
• client_key_file Optional path to local file containing private SSH key to authenticate with
• timeout Timeout between checking SFTP (900 by default)
• folders List of folders to check files in (defaults to single item /)
• patterns List of patterns to check files in (defaults to single pattern *)
• validate_known_hosts Whether to validate known hosts or not
• checker Check algorithm identifier to be used.

Checker algorithms

Following checker algorithms are available for use:

Default checker algorithm is noop, that only lists files in each SFTP folder, Checker algorithm identified as put_get_del will perform sequence of operations in each folder, An algorithm named attributes will export mtime,atime and size for each file.

Smart date handling in file path

Sometimes either folder name or file name in SFTP can contain date inside, so check folders or patterns should change over time. In this case, following parameters could be set to "true" to trigger smart date handling:

• smart_folder_date -- enables smart date for folders
• smart_pattern_date -- enables smart date for patterns Then, python strftime modifiers can be put into folders or patterns to be replaced with today's date and time values.

For example,

checks:
  - smart_pattern_date: true
    patterns:
      - "*%Y%m%d*"

when called on 31 May, 2021 will match all files that have 20210531 in the file name.

If you need base date to be set to other values than today, use

- base_pattern_date: yesterday
- base_folder_date: '2 days ago'

to set base date to other day when templating. Base date values are parsed with dateparser.

Exported metrics

---

sftp_host_up -- when the SFTP host have been successfully accessed for the last time

Dimensions:

• host Host of SFTP server that is being monitored
• username Name of user used for connection
• state State of connection, can be one of Ok, DNSError, SFTPError

---

sftp_put_file_up -- when the put check have been done successfully for the last time

Dimensions:

• host Host of SFTP server that is being monitored
• folder Folder that have been checked for write-ability
• username Username that have been logging in
• state State of write-ability, one of Ok, Error

---

sftp_get_file_up -- when the get check have been done successfully for the last time

Dimensions:

• host Host of SFTP server that is being monitored
• folder Folder that have been checked for read-ability
• username Username that have been logging in
• state State of write-ability, one of Ok, Corrupted, Error

---

sftp_del_file_up -- when the remove check have been done successfully for the last time

Dimensions:

• host Host of SFTP server that is being monitored
• folder Folder that have been checked for remove-ability
• username Username that have been logging in
• state State of write-ability, one of Ok, Error

---

sftp_last_seen_timestamp -- when the file was spotted on SFTP server last time

Dimensions:

• folder Folder name where file was spotted
• file Name of the file have been spotted
• host Host of SFTP server that housed a file

---

sftp_file_modified_timestamp -- mtime attribute as reported by SFTP server

Dimensions:

• folder Folder name where file was spotted
• file Name of the file have been spotted
• host Host of SFTP server that housed a file

---

sftp_file_access_timestamp -- atime attribute as reported by SFTP server

Dimensions:

• folder Folder name where file was spotted
• file Name of the file have been spotted
• host Host of SFTP server that housed a file

---

sftp_file_size -- size attribute as reported by SFTP server

Dimensions:

• folder Folder name where file was spotted
• file Name of the file have been spotted
• host Host of SFTP server that housed a file

---

License

MIT.