credcat

Bound by sacred cyphers and powered by forgotten rites; access without a path, only a destination. Your vital sigils safe, their essence known to none but their holder, sealed by the magic of pure ignorance.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • Configuration
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Extending access to Keeper secrets manager for api retrival in distributed or disconnected processes. Serves as a quality of life abstraction to diminish the scourge of hard-coded, insecurely handled credentials in our code bases.

(back to top)

Built With

• 

Java is like a bad relationship. It's too object-oriented

(back to top)

Getting Started

Compiling is not necessary as release binaries are available. If you're so inclined the sections below are for you.

Prerequisites

Your going to need a compiler, I recommend anything not Oracle java. Depending on your os, the installation process will vary. Additional packages like maven will be needed to utilize the provided pom file.

CentOS

• bash

  sudo dnf install java-21-openjdk java-21-openjdk-devel maven

Debian

• bash

  sudo apt install maven openjdk-21-jdk-headless

Ubuntu

• bash

  sudo apt install maven openjdk-21-jdk-headless

Windows

• powershell

  winget install maven
  winget install Microsoft.OpenJDK.21
  refreshenv

  $jdk_url = "https://aka.ms/download-jdk/microsoft-jdk-21-windows-x64.msi"
  $java_home = New-Item -ItemType Directory -Path "$env:ProgramFiles\Java" -Force
  $maven_home = New-Item -ItemType Directory -Path "$env:ProgramFiles\Apache\Maven" -Force
  $maven_version = "3.9.16"
  $maven_url = "https://dlcdn.apache.org/maven/maven-3/$maven_version/binaries/apache-maven-$maven_version-bin.zip"
  Start-BitsTransfer -Destination "$env:USERPROFILE\Downloads\jdk-21.msi" -Source $jdk_url
  Start-BitsTransfer -Destination "$env:USERPROFILE\Downloads\maven.zip" -Source $maven_url
  Start-Process -Wait -FilePath msiexec -ArgumentList /i, "$env:USERPROFILE\Downloads\jdk-21.msi", "ADDLOCAL=FeatureMain,FeatureEnvironment,FeatureJarFileRunWith,FeatureJavaHome", 'INSTALLDIR="$java_home"', /quiet -Verb RunAs
  Expand-Archive -DestinationPath "$env:USERPROFILE\Downloads\maven" -Path "$env:USERPROFILE\Downloads\maven.zip"
  $parentDir = Get-ChildItem -Path "$env:USERPROFILE\Downloads\maven" | Select-Object -First 1
  Move-Item -Destination $maven_home -Path "$parentDir\*" -Force
  [Environment]::SetEnvironmentVariable('M2_HOME', $maven_home, [System.EnvironmentVariableTarget]::User)
  [Environment]::SetEnvironmentVariable('MAVEN_HOME', $maven_home, [System.EnvironmentVariableTarget]::User)
  [Environment]::SetEnvironmentVariable('PATH', "$env:PATH;$maven_home\bin", [System.EnvironmentVariableTarget]::User)
  Remove-Item "$env:USERPROFILE\Downloads\jdk-21.msi"
  Remove-Item "$env:USERPROFILE\Downloads\maven.zip"
  Remove-Item "$env:USERPROFILE\Downloads\maven" -Recurse -Force

Installation

1. Clone the repo

   git clone https://github.com/byteskeptical/credcat.git
   cd credcat

2. Compile binary, prepare release

   # build binary
   mvn compile
   
   # create package
   mvn install
   
   # prepare package for official release
   mvn package

3. Run tests, (optional). Making changes, (required)

   mvn test

4. Clean up after yourself

   mvn clean

(back to top)

Configuration

Every knob lives in credcat.properties. All are optional and fall back to sane defaults, so an empty file is a working file. The server.* settings are ignored in stand-alone mode.

# Keeper
keeper.client_key=                  # one time token for dynamic config creation
keeper.config=                      # default device config: a path, raw json, or base64
keeper.config.dir=                  # directory searched for named (configName) configs
keeper.config.env=                  # env var prefix searched for named (configName) configs
keeper.files=                       # default save location (os temp dir when unset)
keeper.storage.persistent=false     # persist SDK config mutations back to the source file

# Files
file.clean=true                     # wipe the files directory recursively on shutdown
file.transport=inline               # disk | inline | none

# Server
server.host=127.0.0.1
server.port=8888
server.max_request_bytes=1048576    # larger request bodies are rejected with a 413
server.threads=                     # worker pool size (defaults to max(8, 2x cpu cores))

A named lookup (configName) is resolved against keeper.config.dir first, then the keeper.config.env prefix; the literal config parameter always wins when both are present, and the keeper.config default backs them all.

Usage

You will need a device config for your KSM application in either base64 or json format. Provide it directly with the config parameter, as a literal value or a path to a file holding one. Skip the config entirely and let credcat mint one on the fly via the one time password feature with the clientKey parameter. When direct or individual handling of device configs is undesired use the configName parameter to switch between pre-defined choices stashed in either a directory or through environment variables. The config, configName and clientKey parameters are your means to alternate between application vaults.

Pass one or more of either titles and/or record uid's to retrieve multiple records at once. Exact matches only.

Attached files are handed back however your deployment prefers, set globally with the file.transport property or overridden per-request with fileTransport:

• disk written to the save location, whose path is returned in the response.

• inline base64 encoded straight into the response; nothing touches the disk.

• none skipped entirely; only the file's metadata comes back.

  Usage: java -jar credcat.jar [ -server | '{ "config": ".keeper/config.base64", "titles": ["RECORD_TITLE"], "uids": ["RECORD_UID"] }' ]

1. Payload can be any of the following.

   ADVANCED='{ "clientKey": "7dae669a419ee250d0fd0e12d527f5f1", "config": "config.base64", "fileTransport": "disk", "saveLocation": "/mnt/share/keeper", "titles": ["development ldap"], "uids": ["chnmFhEC38YCHhNY1pA8Vg"] }'
   NAMED='{ "configName": "production", "titles": ["Production ClickToCall API Key", "development ldap"] }'
   TITLE_ONLY='{ "config": ".keeper/config.base64", "titles": ["Production ClickToCall API Key", "development ldap"] }'
   UID_ONLY='{ "config": ".keeper/config.base64", "fileTransport": "disk", "uids": ["7bN_ceW-p3_alVUNmI09Tw", "chnmGhEC39YCHhNy1pA8vg"] }'

2. Whether passing title or uid, records are returned nested under its respective uid. Using the disk transport:

   java -cp "target/classes:target/dependency/*" com.byteskeptical.credcat.SecretsService "$ADVANCED"
   java -jar target/credcat.jar "$UID_ONLY"

   INFO: {
     "7bN_ceW-p3_alVUNmI09Tw" : {
       "fields" : {
         "password" : [ "bingbangboomdongle" ],
         "login" : [ "ldaptest" ]
       },
       "files" : [ ],
       "title" : "development ldap",
       "type" : "login"
     },
     "chnmGhEC39YCHhNy1pA8vg" : {
       "fields" : {
         "password" : [ "be0d988f-063c-d654-ad1b-a54337f87233" ],
         "login" : [ "integration.ucaas.call.metadata" ],
         "fileref" : [ "3HcX3vCCvHBTBcOqCgCnsQ", "cGBiPmG_9GlZszFbsQmJea" ]
       },
       "files" : [ {
         "name" : "ascii-art.txt",
         "path" : "/tmp/credcat_8f3a1c20-5e7b-4a9d-bd11-2c6f0e9a4477/ascii-art.txt",
         "mimeType" : "text/plain",
         "size" : 318
       }, {
         "name" : "integration.ucaas.call.metadata.PNG",
         "path" : "/tmp/credcat_8f3a1c20-5e7b-4a9d-bd11-2c6f0e9a4477/integration.ucaas.call.metadata.PNG",
         "mimeType" : "image/png",
         "size" : 20480
       } ],
       "notes" : "VALUE = x-ClickToCall-APIKey:be0d988f-063c-d654-ad1b-a54337f87233",
       "title" : "Production ClickToCall API Key",
       "type" : "login"
       }
     }
   }

   The default inline transport trades a file path for base64 content, leaving nothing on the host:

   "files" : [ {
     "content" : "ICAgIC9cX18vXAogICAoIC1fLSApCiAgIC8gPiA+IFwK",
     "mimeType" : "text/plain",
     "name" : "ascii-art.txt",
     "size" : 318
   } ]

3. Running in server mode accepts the same request payload, passed by the http client of your choice. You can set your preferred host and port in the credcat properties file.

   java -cp "target/classes:target/dependency/*" -server
   java -jar target/credcat.jar -server

   curl -d "$UID_ONLY" -H 'Content-Type: application/json' -s -XPOST http://127.0.0.1:8888/api/getSecrets
   curl -H 'Content-Type: application/json' -s http://127.0.0.1:8888/api/getVersion

(back to top)

Roadmap

• Handle all field types including files & notes
• Handle title & uid searches
• Inline and metadata-only file transports for read-only & ephemeral hosts
• Named config resolution by directory or environment
• Per-request transport & save-location overrides
• Retrieve more than one record in a single request
• Support stand-alone and server modes

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the project_license. See LICENSE for more information.

(back to top)

Contact

byteskeptical - @byteskeptical - bug@byteskeptical.com

Project Link: https://github.com/byteskeptical/credcat

(back to top)

Acknowledgments

• @byteskeptical

(back to top)