# Installation

## From source

Before you start, make sure you have the following requirements:

- Go 1.22 or higher
- Make

```bash
git clone https://github.com/projectdiscovery/katana.git
cd katana
go build
./katana -h

go install github.com/projectdiscovery/katana/cmd/katana@latest

docker pull projectdiscovery/katana

katana -h

katana is a fast crawler focused on automation in the field of security testing.

Usage:
  katana [flags]

Flags:
INPUT:
   -u, -list string[]  target url / list to crawl
   -r, -resume string   resume scan using resume.cfg
   -e, -exclude string  exclude host matching specified filter ('cdn', 'private-ips', cidr, ip, port, host, protocol, extension, path, query, length, depth, regex)

CONFIGURATION:
   -d, -depth int              maximum depth to crawl (default 3)
   -jc, -js-crawl              enable endpoint parsing / crawling in javascript file
   -jsl, -js-limit int         limit the number of javascript files to parse (default 100)
   -m, -strategy string        crawl strategy. depth-first (dfs) or breadth-first (bfs) (default "bfs")
   -X, -method string          request method (GET, POST, HEAD, OPTIONS, PUT, PATCH, DELETE, CONNECT, TRACE, CUSTOM) (default "GET")
   -H, -headers string[]       custom header/cookie to include in all http request in header:value format (file)
   -ct, -crawl-duration value  maximum duration to crawl the target for (s, m, h, d) (default 0)
   -ef, -extension-filter string[]  filter to only crawl specified extensions
   -em, -extension-match string[]   match specified extensions
   -iq, -ignore-query          ignore query strings in URLs
   -irr, -ignore-regex string  ignore URLs matching this regex
   -kf, -known-files string    enable crawling of known files (all, robotstxt, sitemapxml)
   -mrs, -max-response-size int  maximum response size to read (default 9223372036854775807)
   -timeout int                time to wait for request in seconds (default 10)
   -aff, -automatic-form-fill  enable automatic form filling
   -fx, -form-extraction       extract form, input, textarea & select elements in jsonl output
   -retry int                  number of times to retry the request (default 1)
   -proxy string[]             http/socks5 proxy to use (list of proxies)
   -Hl, -header-line           use header:value format for headers
   -config string              path to the katana configuration file
   -fc, -form-config string    path to a custom form configuration file
   -fl, -field strings         field to fill in form (name, value)
   -cs, -crawl-scope string[]  in scope url regex to be followed by crawler
   -do, -crawl-out-scope       crawl out of scope URLs
   -nc, -no-color              disable colors in output
   -silent                     display output only
   -v, -verbose                display verbose output
   -version                    display project version
   -hc, -health-check          run health check
   -elog, -error-log string    file to write sent requests error log

FILTER:
   -mr, -match-regex string[]     regex or list of regex to match on output url (cli, file)
   -fr, -filter-regex string[]   regex or list of regex to filter on output url (cli, file)
   -fq, -filter-qr string[]      filter url with query parameters matching regex
   -sf, -scope-filter string[]   filter scope urls with regex
   -s, -strategy string          crawl strategy. depth-first (dfs) or breadth-first (bfs) (default "bfs")
   -f, -field string             field to display in output (url,path,fqdn,rdn,rurl,qurl,file,key,value,kv,dir,udir)
   -sf, -store-field string      field to store in per-host input (url,path,fqdn,rdn,rurl,qurl,file,key,value,kv,dir,udir)
   -tl, -tls                     enable tls based routing
   -tlsi, -tls-impersonate       enable experimental client hello impersonation

RATE-LIMIT:
   -c, -concurrency int          number of concurrent fetchers to use (default 10)
   -p, -parallelism int          number of concurrent requests per host (default 10)
   -rd, -delay int               request delay between each request in seconds
   -rl, -rate-limit int          maximum requests to send per second (default 150)
   -rlm, -rate-limit-minute int  maximum number of requests to send per minute

UPDATE:
   -up, -update                 update katana to latest version
   -duc, -disable-update-check  disable automatic katana update check

OUTPUT:
   -o, -output string                file to write output to
   -sr, -store-response              store http requests/responses
   -srd, -store-response-dir string  save http requests/responses to custom directory
   -j, -jsonl                        write output in jsonl format
   -jc, -jsonl-custom-fields string  custom fields to include in jsonl output
   -system string                    system to use for headless crawling (headless, chrome, chromium)
   -system-id string                 system id to use for headless crawling
   -headless                        enable headless hybrid crawling (experimental)
   -sc, -show-config                show the katana configuration
   -ss, -show-scope                 print default scope filters
   -s, -stats                       display stats about the running crawl
   -srd, -store-response-dir string  save http requests/responses to custom directory
   -sr, -store-response              store http requests/responses
   -oD, -output-dir string           directory to write output to
   -match-conditions string          match conditions for output
   -match-condition string           match condition for output
   -match-condition-file string      file containing match conditions for output
   -match-condition-operator string  operator for match conditions (and, or)
   -match-condition-value string     value for match conditions
   -match-condition-field string     field for match conditions
   -match-condition-regex string     regex for match conditions
   -match-condition-regex-file string  file containing regex for match conditions
   -match-condition-regex-operator string  operator for regex match conditions (and, or)
   -match-condition-regex-value string  value for regex match conditions
   -match-condition-regex-field string  field for regex match conditions
   -match-condition-regex-regex string  regex for regex match conditions
   -match-condition-regex-regex-file string  file containing regex for regex match conditions
   -match-condition-regex-regex-operator string  operator for regex regex match conditions (and, or)
   -match-condition-regex-regex-value string  value for regex regex match conditions
   -match-condition-regex-regex-field string  field for regex regex match conditions
   -match-condition-regex-regex-regex string  regex for regex regex match conditions
   -match-condition-regex-regex-regex-file string  file containing regex for regex regex match conditions
   -match-condition-regex-regex-regex-operator string  operator for regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-value string  value for regex regex regex match conditions
   -match-condition-regex-regex-regex-field string  field for regex regex regex match conditions
   -match-condition-regex-regex-regex-regex string  regex for regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-file string  file containing regex for regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-operator string  operator for regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-value string  value for regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-field string  field for regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex string  regex for regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-operator string  operator for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions (and, or)
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-value string  value for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-field string  field for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex string  regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex-file string  file containing regex for regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex regex match conditions
   -match-condition-regex-regex-regex-regex-regex-regex-regex-regex-regex-regex```typescript
import { loadSecrets } from "@envsec/sdk";

// Load and inject into process.env
await loadSecrets({ context: "myapp.dev", inject: true });

// Or use the client for full control
import { EnvsecClient } from "@envsec/sdk";
const client = await EnvsecClient.create({ context: "myapp.dev" });
const apiKey = await client.get("api.key");
await client.close();

Eine laufende D-Bus-Sitzung und ein Keyring-Daemon (z. B. `gnome-keyring-daemon`) müssen aktiv sein. Die meisten Desktop-Umgebungen erledigen dies automatisch.

### Windows

Keine zusätzlichen Abhängigkeiten. Verwendet den integrierten Windows-Anmeldeinformations-Manager über `cmdkey` und PowerShell.

## Installation

### Homebrew (macOS / Linux)```bash
brew tap davidnussio/homebrew-tap
brew install envsec

### npx (ohne Installation)```bash
npx envsec

## Verwendung

Die meisten Befehle erfordern einen Kontext, der mit `--context` (oder `-c`) angegeben wird.
Ein Kontext ist ein frei wählbares Label zum Gruppieren von Geheimnissen — z. B. `myapp.dev`, `stripe-api.prod`, `work.staging`.

### Globale Optionen

Diese Optionen sind für alle Befehle verfügbar:

- `--context`, `-c` — Kontextname (z. B. `myapp.dev`, `stripe-api.prod`). Liest auch die Umgebungsvariable `ENVSEC_CONTEXT`
- `--debug`, `-d` — Debug-Logging aktivieren
- `--json` — Ausgabe im JSON-Format für Skripte
- `--db` — Pfad zur SQLite-Datenbankdatei (Standard: `~/.envsec/store.sqlite`). Liest auch die Umgebungsvariable `ENVSEC_DB`

### Benutzerdefinierter Datenbankpfad

Standardmäßig werden Metadaten unter `~/.envsec/store.sqlite` gespeichert. Sie können dies mit `--db` oder der Umgebungsvariable `ENVSEC_DB` überschreiben:```bash
# Use a project-local database
envsec --db ./local-store.sqlite -c myapp.dev list

# Or via environment variable
export ENVSEC_DB=/shared/team/envsec.sqlite
envsec -c myapp.dev list

### Einen Secret abrufen

Ruft einen Secret-Wert aus dem OS-Anmeldeinformationsspeicher ab.

- `<key>` — Name des Secret-Schlüssels, der abgerufen werden soll
- `--quiet`, `-q` — Nur den Rohwert ausgeben (keine Warnungen oder zusätzliche Ausgabe)
- `--json` — Ausgabe im JSON-Format (enthält Kontext, Schlüssel, Wert, expires_at)```bash
envsec -c myapp.dev get api.key

# Print only the raw value (no warnings or extra output)
envsec -c myapp.dev get api.key --quiet
envsec -c myapp.dev get api.key -q

### Geheimnis umbenennen

Benennen Sie einen geheimen Schlüssel im selben Kontext um. Der Wert und die Ablauf-Metadaten bleiben erhalten.

- `<old-key>` — Aktueller Name des geheimen Schlüssels
- `<new-key>` — Neuer Name des geheimen Schlüssels
- `--force`, `-f` — Ziel überschreiben, falls es bereits existiert```bash
# Rename a key
envsec -c myapp.dev rename old.key new.key

# Overwrite target if it already exists
envsec -c myapp.dev rename old.key existing.key --force

### Alle Kontexte auflisten

Alle verfügbaren Kontexte mit Geheimnisanzahl auflisten.

- `--json` — Ausgabe im JSON-Format```bash
# Without --context, lists all available contexts with secret counts
envsec list

### Geheimnisse zwischen Kontexten verschieben

Verschiebt Geheimnisse von einem Kontext in einen anderen. Die Quell-Geheimnisse werden nach dem Verschieben entfernt.

- `<pattern>` — Glob-Muster oder exakter Schlüssel zum Verschieben (optional, wenn `--all` verwendet wird)
- `--to`, `-t` — Zielkontext, in den die Geheimnisse verschoben werden sollen
- `--all` — Verschiebt alle Geheimnisse aus dem Quellkontext
- `--force`, `-f` — Überschreibt vorhandene Geheimnisse im Zielkontext
- `--yes`, `-y` — Bestätigungsabfrage überspringen```bash
# Move a single secret
envsec -c myapp.dev move api.token --to myapp.prod

# Move secrets matching a glob pattern
envsec -c myapp.dev move "redis.*" --to myapp.prod -y

# Move all secrets from one context to another
envsec -c myapp.dev move --all --to myapp.prod -y

# Overwrite existing secrets in the target context
envsec -c myapp.dev move "redis.*" --to myapp.prod --force -y

### Einen Befehl mit Geheimnissen ausführen

Führen Sie einen Befehl aus, bei dem geheime Werte über Platzhalter interpoliert oder als Umgebungsvariablen injiziert werden.

- `<command>` — Auszuführender Befehl. Verwenden Sie `{key}`-Platzhalter für die Interpolation von Geheimnissen
- `--inject`, `-i` — Alle Kontext-Geheimnisse als Umgebungsvariablen injizieren (`KEY.NAME` → `KEY_NAME`)
- `--save`, `-s` — Diesen Befehl für spätere Verwendung speichern
- `--name`, `-n` — Name für den gespeicherten Befehl (wird interaktiv abgefragt, wenn er mit `--save` weggelassen wird)```bash
# Placeholders {key} are resolved with secret values before execution
envsec -c myapp.dev run 'curl {api.url} -H "Authorization: Bearer {api.token}"'

# Any {dotted.key} in the command string is replaced with its value
envsec -c myapp.prod run 'psql {db.connection_string}'

# Inject ALL context secrets as environment variables (KEY.NAME → KEY_NAME)
envsec -c myapp.dev run --inject 'node server.js'
envsec -c myapp.dev run -i 'docker compose up'

# Combine --inject with placeholders
envsec -c myapp.dev run --inject 'curl {api.url} -H "Authorization: Bearer $API_TOKEN"'

# Save the command for later use with --save (-s) and --name (-n)
envsec -c myapp.dev run --save --name deploy 'kubectl apply -f - <<< {k8s.manifest}'

# If you use --save without --name, you'll be prompted interactively
envsec -c myapp.dev run --save 'psql {db.connection_string}'

### Gespeicherte Befehle

Gespeicherte Befehle liegen unter dem Unterbefehl `cmd`, getrennt von geheimen Operationen.

#### cmd list

Listet alle gespeicherten Befehle auf.```bash
envsec cmd list

#### cmd search

Durchsucht gespeicherte Befehle nach Name oder Befehlszeichenfolge.

- `<pattern>` — Suchmuster
- `--name`, `-n` — Nur in Befehlsnamen suchen
- `--command`, `-m` — Nur in Befehlszeichenfolgen suchen```bash
envsec cmd search psql

# Search only by name
envsec cmd search deploy -n

# Search only by command string
envsec cmd search kubectl -m

### Eine .env-Datei generieren

Exportieren Sie alle Geheimnisse aus einem Kontext in eine `.env`-Datei.

- `--output`, `-o` — Pfad der Ausgabedatei (Standard: `.env`)```bash
# Creates .env with all secrets from the context
envsec -c myapp.dev env-file

# Specify a custom output path
envsec -c myapp.dev env-file --output .env.local

Unterstützte Shells: `bash` (Standard), `zsh`, `fish`, `powershell`. Schlüssel werden in `UPPER_SNAKE_CASE` umgewandelt (z. B. `api.token` → `API_TOKEN`). Die Ausgabe erfolgt auf stdout, sodass sie direkt an `eval` weitergeleitet oder gesourced werden kann – es wird keine Datei auf die Festplatte geschrieben.

### Eine auf Geheimnisse begrenzte Shell-Sitzung starten

Starte eine interaktive Subshell, in die alle Geheimnisse aus dem Kontext als
Umgebungsvariablen injiziert werden. Wenn du `exit` ausführst, sind die Geheimnisse weg – keine Bereinigung erforderlich.

- `--shell`, `-s` — Zu startende Shell (`bash`, `zsh`, `fish`, `powershell`). Standard: automatische Erkennung
- `--no-inherit` — Übernimmt keine Umgebungsvariablen der übergeordneten Prozesse
- `--quiet`, `-q` — Unterdrückt das Start-/Beendigungsbanner```bash
envsec -c myapp.dev shell

## 🛡️ Sicherheitshinweis

Bitte stellen Sie sicher, dass Sie die neueste Version des Tools verwenden, um von den neuesten Sicherheitspatches und Fehlerbehebungen zu profitieren. Überprüfen Sie regelmäßig die offizielle Repository-Seite auf Updates.

## 📦 Installation

Sie können das Tool mit den folgenden Befehlen installieren:

```bash
git clone https://github.com/example/tool.git
cd tool
pip install -r requirements.txt

python tool.py --help

▶ envsec shell — context: myapp.dev (8 secrets loaded)
Type 'exit' or press Ctrl+D to leave the session.

(envsec:myapp.dev) ~ $ echo $DATABASE_URL
postgres://user:pass@localhost/mydb

(envsec:myapp.dev) ~ $ exit
→ Exiting envsec shell — secrets cleared.
```
```
## 🛡️ Sicherheitsfunktionen

- **Verschlüsselung**: Alle Daten werden mit AES-256-GCM verschlüsselt, bevor sie gespeichert oder übertragen werden.
- **Authentifizierung**: Unterstützt Multi-Faktor-Authentifizierung (MFA) und Single Sign-On (SSO) über SAML 2.0 und OAuth 2.0.
- **Zugriffskontrolle**: Rollenbasierte Zugriffskontrolle (RBAC) mit granularen Berechtigungen für jede Ressource.
- **Audit-Protokollierung**: Umfassende Protokollierung aller Benutzeraktionen und Systemereignisse für Compliance- und Forensik-Zwecke.
- **Sichere Konfiguration**: Härtungskonfigurationen für gängige Server- und Datenbankbereitstellungen enthalten.
- **Regelmäßige Updates**: Automatische Sicherheitsupdates und Schwachstellen-Scans, um die neuesten Bedrohungen zu adressieren.

## 📦 Installation

### Voraussetzungen

- **Betriebssystem**: Ubuntu 20.04+, Debian 11+, oder CentOS 8+
- **Python**: 3.8 oder höher
- **Node.js**: 14.x oder höher (für das Web-Interface)
- **Docker**: 20.10+ (optional, für Container-Bereitstellung)
- **Mindestens 4 GB RAM** und 20 GB freier Speicherplatz

### Schnellstart

```bash
# Repository klonen
git clone https://github.com/example/security-tool.git
cd security-tool

# Abhängigkeiten installieren
pip install -r requirements.txt
npm install --prefix frontend

# Konfigurationsdatei erstellen
cp config.example.yml config.yml
# Bearbeiten Sie config.yml mit Ihren Einstellungen

# Datenbank initialisieren
python manage.py migrate

# Dienst starten
python manage.py runserver 0.0.0.0:8000
```

### Docker-Bereitstellung

```bash
# Docker-Image bauen
docker build -t security-tool:latest .

# Container ausführen
docker run -d -p 8000:8000 \
  -v /path/to/config.yml:/app/config.yml \
  -v /path/to/data:/app/data \
  --name security-tool \
  security-tool:latest
```

## 🚀 Verwendung

### Web-Interface

Nach dem Start ist das Web-Interface unter `http://localhost:8000` erreichbar. Standard-Anmeldedaten:

- **Benutzername**: `admin`
- **Passwort**: `admin123` (bitte nach dem ersten Login ändern!)

### API-Nutzung

Die REST-API ist unter `/api/v1/` verfügbar. Beispiel für einen API-Aufruf:

```bash
curl -X GET "http://localhost:8000/api/v1/vulnerabilities" \
  -H "Authorization: Bearer <IHR_TOKEN>"
```

### Befehlszeilen-Tool

Das CLI-Tool bietet erweiterte Funktionen für die Automatisierung:

```bash
# Schwachstellen scannen
python cli.py scan --target example.com --output report.json

# Bericht generieren
python cli.py report --format pdf --output report.pdf

# Regeln aktualisieren
python cli.py update-rules
```

## ⚙️ Konfiguration

Die Hauptkonfigurationsdatei `config.yml` steuert alle Aspekte des Tools. Wichtige Abschnitte:

```yaml
server:
  host: 0.0.0.0
  port: 8000
  debug: false

database:
  engine: postgresql
  host: localhost
  port: 5432
  name: security_tool
  user: admin
  password: secure_password

security:
  encryption_key: "Ihr-256-Bit-Schlüssel"
  jwt_secret: "Ihr-JWT-Geheimnis"
  session_timeout: 30  # Minuten

notifications:
  email:
    enabled: true
    smtp_host: smtp.example.com
    smtp_port: 587
    from: [email protected]
  slack:
    enabled: false
    webhook_url: ""
```

## 📊 Berichterstattung

Das Tool generiert detaillierte Berichte in mehreren Formaten:

- **PDF**: Für formelle Dokumentation und Compliance-Zwecke
- **HTML**: Interaktive Berichte mit Diagrammen und Filtern
- **CSV**: Für die Datenanalyse in Tabellenkalkulationen
- **JSON**: Für die Integration in andere Systeme

### Beispielbericht

```json
{
  "scan_id": "abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "target": "example.com",
  "vulnerabilities": [
    {
      "id": "CVE-2024-1234",
      "severity": "high",
      "description": "SQL-Injection in der Anmeldeseite",
      "status": "open"
    }
  ]
}
```

## 🔧 Fehlerbehebung

### Häufige Probleme

| Problem | Lösung |
|---------|--------|
| Verbindungsfehler zur Datenbank | Überprüfen Sie die Datenbankkonfiguration in `config.yml` und stellen Sie sicher, dass der Dienst läuft |
| Port bereits belegt | Ändern Sie den Port in `config.yml` oder stoppen Sie den Prozess, der den Port belegt |
| Berechtigungsfehler | Stellen Sie sicher, dass der Benutzer über die erforderlichen Lese-/Schreibrechte für das Datenverzeichnis verfügt |
| Langsame Scan-Leistung | Erhöhen Sie die Thread-Anzahl in den Leistungseinstellungen oder reduzieren Sie die Scan-Tiefe |

### Protokolle

Protokolle finden Sie unter `logs/` im Installationsverzeichnis. Für detaillierte Debug-Informationen setzen Sie `debug: true` in `config.yml`.

## 🤝 Mitwirken

Wir begrüßen Beiträge von der Community! So können Sie helfen:

1. **Fehler melden**: Öffnen Sie ein Issue auf GitHub mit einer detaillierten Beschreibung
2. **Code beitragen**: Forken Sie das Repository und senden Sie Pull Requests
3. **Dokumentation**: Verbessern Sie die Dokumentation oder übersetzen Sie sie in andere Sprachen
4. **Feedback**: Teilen Sie Ihre Erfahrungen und Vorschläge im Diskussionsforum

### Entwicklungsumgebung einrichten

```bash
# Entwicklungsabhängigkeiten installieren
pip install -r requirements-dev.txt
npm install --prefix frontend

# Tests ausführen
python -m pytest tests/
npm test --prefix frontend

# Linting
flake8 .
eslint frontend/src/
```

## 📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Informationen finden Sie in der Datei [LICENSE](https://github.com/davidnussio/envsec/blob/main/LICENSE).

## 📞 Support

- **Dokumentation**: [docs.example.com](https://docs.example.com)
- **Community-Forum**: [forum.example.com](https://forum.example.com)
- **E-Mail**: [email protected]
- **Discord**: [Einladungslink](https://discord.gg/example)

## 🙏 Danksagungen

- Allen Mitwirkenden und Maintainern dieses Projekts
- Der Open-Source-Community für ihre wertvollen Tools und Bibliotheken
- Allen Benutzern, die Feedback und Verbesserungsvorschläge gegeben haben

---

**Hinweis**: Dieses Tool ist für Bildungs- und Sicherheitsforschungszwecke gedacht. Stellen Sie sicher, dass Sie die geltenden Gesetze und Vorschriften einhalten, wenn Sie es verwenden. Der Autor übernimmt keine Haftung für Missbrauch oder Schäden, die durch die Verwendung dieses Tools entstehen.
``````bash
# Force a specific shell
envsec -c myapp.dev shell --shell zsh

# Only envsec secrets in env (no parent variables, except PATH)
envsec -c myapp.dev shell --no-inherit

# Suppress the startup/exit banner
envsec -c myapp.dev shell --quiet
```
Die Variable `ENVSEC_CONTEXT` ist innerhalb der Sitzung immer gesetzt, sodass du sie in Skripten oder bei der Anpassung der Eingabeaufforderung referenzieren kannst.

### Geheimnisse aus einer .env-Datei laden

Importiere Geheimnisse aus einer `.env`-Datei in einen Kontext.

- `--input`, `-i` — Pfad zur Eingabe-`.env`-Datei (Standard: `.env`)
- `--force`, `-f` — Vorhandene Geheimnisse ohne Rückfrage überschreiben
- `--batch`, `-b` — Batch-Modus: Datenbank-Persistenz aufschieben, bis alle Geheimnisse importiert sind```bash
# Import secrets from .env into the context
envsec -c myapp.dev load

# Specify a custom input file
envsec -c myapp.dev load --input .env.local

# Overwrite existing secrets without warning
envsec -c myapp.dev load --force
```
Schlüssel werden von `UPPER_SNAKE_CASE` in `dotted.lowercase` umgewandelt (z. B. `API_TOKEN` → `api.token`). Wenn ein Schlüssel bereits existiert, wird er mit einer Warnung übersprungen, sofern nicht `--force` (`-f`) angegeben ist.

### Geheimnisse teilen (GPG-verschlüsselt)

Verschlüsselt alle Geheimnisse aus einem Kontext für ein Teammitglied mit GPG.

- `--encrypt-to` — GPG-Empfängerschlüssel (E-Mail, Schlüssel-ID oder Fingerabdruck), für den verschlüsselt werden soll
- `--output`, `-o` — Pfad der Ausgabedatei (Standard: stdout). Verwenden Sie `-` für explizit stdout
- `--json` — JSON-Format innerhalb der verschlüsselten Nutzdaten verwenden (Standard: `.env`-Format)```bash
# Encrypt all secrets from a context for a team member
envsec -c myapp.dev share --encrypt-to [email protected]

# Save encrypted output to a file
envsec -c myapp.dev share --encrypt-to [email protected] -o secrets.enc

# Use JSON format inside the encrypted payload
envsec -c myapp.dev --json share --encrypt-to [email protected] -o secrets.enc
```
Der Empfänger kann mit `gpg --decrypt secrets.enc` entschlüsseln und das Ergebnis in `envsec load` pipen. Standardmäßig verwendet die verschlüsselte Nutzlast das `.env`-Format (`KEY="value"`); mit `--json` wird ein strukturiertes JSON-Objekt verwendet. Erfordert, dass GPG installiert ist und sich der öffentliche Schlüssel des Empfängers in Ihrem Schlüsselbund befindet.

### Geheimnisse auf Ablauf prüfen

Prüfen Sie auf abgelaufene oder bald ablaufende Geheimnisse und verfolgte `.env`-Dateiexporte.

- `--within`, `-w` — Zeigt Geheimnisse, die innerhalb dieser Dauer ablaufen (Standard: `30d`). Verwenden Sie `0d`, um nur bereits abgelaufene anzuzeigen
- `--json` — Ausgabe im JSON-Format```bash
# Check for expired or expiring secrets in a context (default window: 30 days)
envsec -c myapp.dev audit

# Specify a custom window
envsec -c myapp.dev audit --within 7d

# Show only already-expired secrets
envsec -c myapp.dev audit --within 0d

# Audit across all contexts (omit --context)
envsec audit

# JSON output
envsec -c myapp.dev audit --json
```
Secrets with an `--expires` duration set via `envsec add` are tracked in metadata. The `audit` command scans for secrets that are already expired or will expire within the specified window. The `get` and `list` commands also display expiry warnings inline.

The `audit` command also tracks generated `.env` files. Every time `env-file` is used, the output path, context, and timestamp are recorded. The audit output includes a second section listing these files. If a tracked `.env` file no longer exists on disk, audit automatically removes it from the metadata and reports the cleanup.

### Generate a random secret

Generate a cryptographically secure random secret, optionally storing it.

- `<key>` — Secret key name (optional; omit for standalone password generation)
- `--length`, `-l` — Length of the generated secret (default: `32`)
- `--prefix`, `-p` — Prefix to prepend to the generated secret (e.g. `sk_`)
- `--expires`, `-e` — Expiry duration (e.g. `30m`, `2h`, `7d`, `4w`, `3mo`, `1y`)
- `--alphanumeric`, `-a` — Use only alphanumeric characters `[a-zA-Z0-9]` (default)
- `--special`, `-s` — Include common special characters `[a-zA-Z0-9!@#$%^&*]`
- `--all-chars`, `-A` — Use all printable ASCII characters for maximum entropy```bash
# Generate and store a 32-char alphanumeric secret
envsec -c myapp.dev secret api.key

# Custom length and prefix
envsec -c myapp.dev secret api.key --prefix "sk_" --length 48

# Character sets:
#   --alphanumeric (-a)  [a-zA-Z0-9] (default)
#   --special (-s)       [a-zA-Z0-9] + !@#$%^&*
#   --all-chars (-A)     all printable ASCII
envsec -c myapp.dev secret db.password --special --length 64

# With expiry
envsec -c myapp.dev secret api.key --prefix "sk_" -l 48 --expires 90d

# Standalone password generator (no store, just print)
envsec secret --length 32
envsec secret --special --length 64 --prefix "pk_"
```
Wenn sowohl Kontext als auch Schlüssel angegeben sind, wird der generierte Wert gespeichert und ausgegeben. Ohne eines von beiden geht der Rohwert an stdout – nützlich zum Weiterleiten an `pbcopy`, `xclip` oder andere Tools.

### Interaktive TUI

envsec enthält eine Vollbild-Terminaloberfläche zur interaktiven Verwaltung von Geheimnissen – ohne dass man sich Befehle merken muss.```bash
# Launch the TUI
envsec tui

# Launch with a pre-selected context
envsec -c myapp.dev tui
```
Die TUI bietet acht Bildschirme, die über das Hauptmenü erreichbar sind:

- **Kontexte** — alle Kontexte durchsuchen, aktiven Kontext mit `s` festlegen, Kontext mit `x` löschen, Geheimnisanzahl anzeigen, gesamte Kontexte löschen
- **Geheimnisse** — Geheimnisse in einer Tabelle auflisten, Werte anzeigen, Geheimnisse hinzufügen oder löschen
- **Geheimnis hinzufügen** — interaktives Formular mit maskierter Eingabe und optionaler Ablaufdauer
- **Suche** — Glob-Muster-Suche über Geheimnisse oder Kontexte
- **Gespeicherte Befehle** — gespeicherte Befehlsvorlagen auflisten, anzeigen und löschen
- **Audit** — auf abgelaufene/ablaufende Geheimnisse prüfen, protokollierte `.env`-Dateiexporte überprüfen
- **`.env` importieren** — Geheimnisse aus einer `.env`-Datei in den aktuellen Kontext laden
- **`.env` exportieren** — Geheimnisse in eine `.env`-Datei exportieren (für Audit protokolliert)

Tastaturkürzel:

| Taste | Aktion |
|-----|--------|
| `↑` / `↓` | Menüpunkte und Tabellenzeilen navigieren |
| `Enter` | Auswählen / bestätigen |
| `c` | Kontextansicht öffnen (Hauptmenü) |
| `s` | Ausgewähltes als aktiven Kontext festlegen (Kontextansicht) |
| `x` | Aktiven Kontext löschen (Kontextansicht) |
| `a` | Neues Geheimnis hinzufügen (Geheimnisansicht) |
| `d` | Ausgewähltes Element löschen |
| `r` | Geheimniswert anzeigen (Detailansicht) |
| `Esc` | Zurückgehen / abbrechen |
| `q` | TUI beenden |

### Einrichtung diagnostizieren

Führen Sie Gesundheitschecks aus, um Ihre envsec-Installation zu überprüfen.

- `--json` — Ausgabe im JSON-Format für Skripting```bash
# Run all health checks
envsec doctor

# JSON output for scripting
envsec --json doctor
```
Der Befehl `doctor` überprüft, ob deine envsec-Installation korrekt funktioniert. Er prüft:
- Plattformunterstützung und Node.js-Version
- Verfügbarkeit des Credential-Speichers (macOS Keychain, Linux secret-tool, Windows cmdkey)
- Lese-/Schreibzugriff auf den Keychain
- Datenbankpfad, Berechtigungen und Schema-Integrität
- Verwaiste Secrets (Metadaten ohne Keychain-Eintrag)
- Abgelaufene Secrets
- Umgebungsvariablen (`ENVSEC_DB`, `ENVSEC_CONTEXT`)
- Aktuelle Shell

### Shell-Komplettierungen

envsec unterstützt dynamische Tab-Komplettierung für bash, zsh und fish. Die Komplettierungen sind kontextbewusst: Sie schlagen deine tatsächlichen Kontextnamen, Secret-Keys und gespeicherten Befehlsnamen in Echtzeit vor, indem sie die Metadaten-Datenbank abfragen.```bash
# Bash (add to ~/.bashrc)
eval "$(envsec --completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(envsec --completions zsh)"

# Fish (add to ~/.config/fish/config.fish)
envsec --completions fish | source
```
Was dynamisch vervollständigt wird:
- `--context` / `-c` — listet alle Ihre Kontexte auf
- Secret-Key-Argumente (`get`, `add`, `delete`) — listet Schlüssel für den aktuellen Kontext auf
- `cmd run` / `cmd delete` — listet gespeicherte Befehlsnamen auf
- `--override-context` / `-o` — listet Kontexte für `cmd run` auf
- Unterbefehle, Flags und statische Auswahlmöglichkeiten (Shells usw.) werden ebenfalls vervollständigt

## Vergleich

Wie schneidet envsec im Vergleich zu anderen Tools für die Verwaltung von Umgebungsgeheimnissen ab?

| Funktion | envsec | dotenv / dotenvx | 1Password CLI (`op`) |
|---|---|---|---|
| Secret-Speicherung | OS-Anmeldedatenspeicher (Keychain, Secret Service, Credential Manager) | `.env`-Dateien auf der Festplatte (dotenvx fügt Verschlüsselung hinzu) | 1Password-Cloud-Vault |
| Verschlüsselung im Ruhezustand | An OS delegiert (Keychain, GNOME Keyring, DPAPI) | Keine (dotenv) / ECIES pro Datei (dotenvx) | AES-256 in der 1Password-Cloud |
| Secrets auf der Festplatte | Nie — Werte gehen direkt in den OS-Anmeldedatenspeicher | Immer — `.env`-Dateien sind standardmäßig Klartext | Nie lokal (zur Laufzeit aus der Cloud abgerufen) |
| Offline-Zugriff | Vollständig — Secrets sind lokal im OS-Speicher | Vollständig — Dateien sind lokal | Erfordert Netzwerk (zwischengespeicherte Elemente in der App offline verfügbar) |
| Konto / Abonnement | Keines — kostenlos, Open Source, keine Anmeldung | Kostenlos (dotenv) / kostenlos Open Source (dotenvx) | Bezahltes Abonnement (ab ca. 3 $/Monat privat, ca. 8 $/Benutzer/Monat geschäftlich) |
| Plattformübergreifend | macOS, Linux, Windows | Jede Plattform mit Node.js / jeder Laufzeit (dotenvx) | macOS, Linux, Windows |
| Kontext-/Umgebungsorganisation | Kontexte (z. B. `myapp.dev`, `stripe.prod`) | Separate `.env`-Dateien pro Umgebung | Vaults und Elemente |
| Befehle mit Secrets ausführen | `envsec run` — Platzhalter-Interpolation + `--inject`-Umgebungsvariablen | `dotenvx run -- cmd` — injiziert aus verschlüsselten `.env`-Dateien | `op run -- cmd` — injiziert über Secret-Referenzen |
| Export in `.env`-Datei | `envsec env-file` (für Audit nachverfolgt) | Natives Format — `.env`-Dateien sind die Quelle der Wahrheit | `op inject --out-file` |
| Import aus `.env`-Datei | `envsec load` (mit Konflikterkennung) | N/A — `.env` ist der primäre Speicher | Manuelle Elementerstellung |
| Shell-Umgebungs-Export | `eval $(envsec env)` — bash, zsh, fish, powershell | `dotenvx run` oder `node -r dotenv/config` | `op run --env-file` |
| Interaktive Shell-Sitzung | `envsec shell` — abgegrenzte Subshell mit automatischer Bereinigung | Nicht integriert | Nicht integriert |
| Secret-Suche | Glob-Muster für Schlüssel und Kontexte | Nicht integriert | `op item list --tags/--category`-Filterung |
| Ablauf-/Rotations-Audit | `envsec audit` — abgelaufene, ablaufende, nachverfolgte `.env`-Dateien | Nicht integriert | Watchtower (in der App, nicht CLI) |
| Gespeicherte Befehle | `envsec cmd` — speichern, auflisten, suchen, ausführen, löschen | Nicht integriert | Nicht integriert |
| Secrets verschieben / kopieren | `envsec move` und `envsec copy` zwischen Kontexten | Manuelles Dateikopieren | `op item move` zwischen Vaults |
| Secrets umbenennen | `envsec rename` (bewahrt Wert und Metadaten) | Manuelle Bearbeitung der `.env`-Datei | `op item edit` |
| GPG-verschlüsseltes Teilen | `envsec share --encrypt-to` | Verschlüsselte `.env`-Dateien, die in Git committet werden (dotenvx) | Integriertes Vault-Sharing, Team-Provisionierung |
| Interaktive TUI | `envsec tui` — Vollbild-Terminal-UI | Nicht integriert | Nicht integriert |
| Gesundheitsdiagnose | `envsec doctor` — prüft Plattform, Keychain, DB-Integrität | Nicht integriert | Nicht integriert |
| Shell-Vervollständigung | Dynamisch (Kontexte, Schlüssel, Befehle) für bash, zsh, fish | Nicht integriert | Statische Vervollständigung für bash, zsh, fish, powershell |
| SDK / programmatischer Zugriff | `@envsec/sdk` für Node.js / Bun | `require('dotenv').config()` — Kernanwendungsfall | 1Password-SDKs (Node.js, Python, Go usw.) |
| Team / Mehrbenutzer | GPG-Sharing (manuell) | Git-basiertes Sharing mit verschlüsselten `.env`-Dateien (dotenvx) | Integriertes Team-Management, RBAC, Audit-Logs |
<!-- | CI/CD-Integration | Standard-CLI — funktioniert überall, wo Node.js läuft | `dotenvx run` in jeder CI-Pipeline | Servicekonten, native CI/CD-Integrationen | -->
| Biometrische Authentifizierung | Erbt OS-Biometrie (z. B. macOS-Keychain-Entsperrung) | Keine | Fingerabdruck / Touch ID über App-Integration |
| Metadaten-Nachverfolgung | SQLite (Schlüsselnamen, Zeitstempel — niemals Werte) | Keine | Cloud-basierte Elementhistorie und Audit-Logs |

Kurz gesagt: dotenv ist der einfachste Ansatz (Dateien auf der Festplatte), die 1Password-CLI ist die funktionsreichste für Teams mit Cloud-Synchronisierung und RBAC, und envsec liegt dazwischen — mit nativer OS-Verschlüsselung, null Konten, null Cloud-Abhängigkeiten und einem entwicklerorientierten Workflow, der über das hinausgeht, was `.env`-Dateien leisten können.

## So funktioniert es

Secrets werden im nativen OS-Anmeldedatenspeicher gespeichert. Das Backend wird automatisch basierend auf der Plattform ausgewählt:

| OS      | Backend                        | Tool / API                          |
|---------|--------------------------------|-------------------------------------|
| macOS   | Keychain                       | `security`-CLI                      |
| Linux   | Secret Service API (D-Bus)     | `secret-tool` (libsecret)           |
| Windows | Credential Manager             | `cmdkey` + PowerShell (advapi32)    |

Metadaten (Schlüsselnamen, Zeitstempel) werden in einer SQLite-Datenbank unter `~/.envsec/store.sqlite` gespeichert (konfigurierbar über `--db` oder `ENVSEC_DB`). Schlüssel müssen mindestens einen Punkt als Trennzeichen enthalten (z. B. `service.account`), was der Service-/Account-Struktur des Anmeldedatenspeichers entspricht.

## Sicherheit

envsec basiert auf einem einfachen Prinzip: Ihre Secrets gehören in Ihr OS, nicht in Dotfiles. Jede Designentscheidung geht von dieser Grundlage aus.

### Wie envsec Ihre Secrets schützt

**OS-native Verschlüsselung, null eigene Kryptografie.** Secret-Werte werden direkt in der macOS-Keychain, im GNOME Keyring / KDE Wallet oder im Windows Credential Manager gespeichert. envsec erfindet keine eigene Verschlüsselung — es delegiert an die kampferprobten Anmeldedatenspeicher, die Ihr Betriebssystem bereits bereitstellt, geschützt durch Ihre Benutzersitzung und (unter macOS) die Login-Keychain.

**Volle Unicode-Unterstützung.** Secret-Werte können beliebige Unicode-Zeichen enthalten, einschließlich Emojis und akzentuierter Buchstaben. Werte werden vor der Speicherung im OS-Anmeldedatenspeicher base64-kodiert, wodurch plattformspezifische Kodierungs-Eigenheiten vermieden werden (z. B. hex-kodierte Nicht-ASCII-Ausgabe der macOS-`security`-CLI). Legacy-Klartext-Secrets werden aus Gründen der Abwärtskompatibilität transparent gelesen.

**Secrets berühren die Festplatte nie als Klartext.** Werte gehen direkt von Ihrem Terminal in den OS-Anmeldedatenspeicher. Sie werden niemals in Konfigurationsdateien, Logs oder Zwischenspeicher geschrieben.

**Keine Secrets in der Terminalausgabe.** Die Befehle `list` und `search` zeigen nur Schlüsselnamen an — Werte werden niemals ausgegeben. Dadurch bleiben Secrets aus Scrollback-Puffern, Bildschirmaufnahmen und dem Blickfeld von Mitlesern fern.

**Sichere Befehlsausführung.** Der Befehl `run` injiziert Secrets als Umgebungsvariablen des Kindprozesses, anstatt sie in die Befehlszeichenfolge zu interpolieren. Dadurch erscheinen Secret-Werte nicht in der `ps`-Ausgabe oder im Shell-Verlauf. Wenn ein referenziertes Secret fehlt, wird der Befehl vollständig blockiert — keine teilweise Ausführung mit unvollständigen Anmeldedaten.

**Eingabevalidierung und Injektionsschutz.** Kontextnamen werden gegen eine strenge Allowlist validiert (alphanumerisch, Punkte, Bindestriche, Unterstriche) mit Prüfungen auf Pfad-Traversal und Prototype-Pollution. Alle SQLite-Abfragen verwenden vorbereitete Anweisungen mit Bind-Parametern, was SQL-Injection verhindert. PowerShell-Argumente unter Windows werden maskiert, um Befehlsinjektion zu verhindern.

**Restriktive Dateiberechtigungen.** Das Metadatenverzeichnis (`~/.envsec/`) wird mit `0700`-Berechtigungen und die SQLite-Datenbank mit `0600` erstellt, wodurch der Zugriff auf den besitzenden Benutzer beschränkt wird.

### Bekannte Einschränkungen und Verbesserungsbereiche

Wir glauben an Transparenz darüber, was envsec noch nicht abdeckt. Dies sind echte Kompromisse, keine Fehler — und sie zu verstehen hilft Ihnen, fundierte Entscheidungen zu treffen.

**Metadaten sind sichtbar.** Die SQLite-Datenbank unter `~/.envsec/store.sqlite` speichert Schlüsselnamen, Kontextnamen und Zeitstempel — niemals Secret-Werte, aber genug, um aufzudecken, *welche* Secrets existieren. Gespeicherte Befehlsvorlagen (mit `{key}`-Platzhaltern) werden dort ebenfalls gespeichert. Wenn Ihnen die Vertraulichkeit der Metadaten wichtig ist, stellen Sie sicher, dass Ihr Home-Verzeichnis auf einem verschlüsselten Volume liegt.

**`env-file`-Exporte sind Klartext.** Der Befehl `env-file` schreibt Secret-Werte in eine `.env`-Datei auf der Festplatte. Dies ist von Natur aus sensibel — behandeln Sie die Ausgabedatei entsprechend und committen Sie sie niemals in die Versionskontrolle. Betrachten Sie sie als Komfort-Brücke, nicht als Speichermechanismus.

**Shell-Ausführung birgt inhärentes Risiko.** Der Befehl `run` übergibt Ihre Befehlsvorlage an `/bin/sh` (oder `cmd.exe` unter Windows). Wenn die Vorlage selbst aus nicht vertrauenswürdiger Eingabe stammt, ist Shell-Injection möglich. Führen Sie nur Befehlsvorlagen aus, die Sie selbst geschrieben haben oder denen Sie vertrauen.

**Keine kontextübergreifende Zugriffskontrolle.** Jeder Prozess, der als Ihr OS-Benutzer läuft, kann alle Secrets über alle Kontexte hinweg lesen. envsec verlässt sich auf die OS-Ebene der Benutzerisolierung — es fügt keine eigene Autorisierungsebene zwischen Kontexten hinzu.

**Linux-Headless-Umgebungen.** Unter Linux ist envsec von einer aktiven D-Bus-Sitzung und einem Keyring-Daemon (z. B. `gnome-keyring-daemon`) abhängig. In Containern oder Headless-Servern ohne grafische Sitzung kann der Keyring nicht verfügbar sein oder Secrets mit schwächerem Schutz speichern.

**Verschlüsselung hängt von Ihrem OS ab.** envsec fügt keine zusätzliche Ruhezustands-Verschlüsselung über das hinaus hinzu, was der native Anmeldedatenspeicher bietet. Auf Systemen ohne vollständige Festplattenverschlüsselung könnte ein Angreifer mit physischem Zugriff potenziell Secrets aus der Keychain extrahieren. Wir empfehlen die Aktivierung der vollständigen Festplattenverschlüsselung (FileVault, LUKS, BitLocker) für den stärksten Schutz.

## Entwicklung

### Voraussetzungen

- Node.js >= 22
- pnpm

Die Core-, SDK-, CLI- und TUI-Pakete verwenden Effect 4 und sind derzeit auf
`4.0.0-rc.112` festgelegt. Halten Sie die Effect- und `@effect/platform-node`-Versionen
im gesamten Workspace ausgerichtet, solange Effect 4 den Release-Candidate-Status hat.

### Einrichtung```bash
git clone https://github.com/davidnussio/envsec.git
cd envsec
pnpm install
pnpm run build
```
### Projektstruktur```
packages/
  cli/     → envsec CLI (published as `envsec`)
  sdk/     → Node.js/Bun SDK (published as `@envsec/sdk`)
  core/    → Core engine, shared by CLI and SDK (published as `@envsec/core`)
  tui/     → Interactive terminal UI (published as `@envsec/tui`)
apps/
  website/ → Documentation website
```
### Allgemeine Befehle```bash
# Build all packages
pnpm run build

# Lint and format check (all packages)
pnpm run check

# Auto-fix lint and formatting
pnpm run fix

# Run package unit and contract tests
pnpm run test:unit

# Run the CLI end-to-end suite with isolated database and credential fixtures
pnpm --filter envsec test

# Release (build + changeset publish)
pnpm run release
```
Die isolierte E2E-Suite greift niemals auf den nativen Anmeldedatenspeicher zu. Um den echten OS-Adapter unter macOS oder Linux zu testen, muss zuerst gebaut und explizit zugestimmt werden:```bash
ENVSEC_E2E_CLI="$PWD/packages/cli/dist/main.js" \
  ENVSEC_E2E_ISOLATED=0 \
  pnpm --filter envsec test
```
Native-E2E-Tests verwenden dedizierte `test.e2e*`-Kontexte und entfernen diese anschließend.

### Lokal ausführen, ohne zu installieren

Erstellen Sie einen temporären Alias, um den lokalen Build so zu verwenden, als wäre er global installiert:```bash
# Bash / Zsh
alias envsec="node $(pwd)/packages/cli/dist/main.js"

# Fish
alias envsec "node (pwd)/packages/cli/dist/main.js"
```
### Shell-Vervollständigungen lokal testen

Nach dem Erstellen und Einrichten des Alias laden Sie die Vervollständigungen in Ihrer aktuellen Sitzung:```bash
# Bash
alias envsec="node $(pwd)/packages/cli/dist/main.js"
eval "$(envsec --completions bash)"

# Zsh
alias envsec="node $(pwd)/packages/cli/dist/main.js"
eval "$(envsec --completions zsh)"

# Fish
alias envsec "node (pwd)/packages/cli/dist/main.js"
envsec --completions fish | source
```
Drücken Sie dann TAB nach `envsec -c `, um Ihre Kontexte zu sehen, oder nach `envsec -c myapp.dev get `, um Secret-Keys zu sehen.

### Tests ausführen

End-to-End-Integrationstests decken den vollständigen CLI-Lebenszyklus ab (add, get, list, search, env-file, load, delete, run, cmd, audit, share, completions).```bash
# Build first
pnpm run build

# macOS / Linux
bash packages/cli/test/e2e-test.sh

# Windows (PowerShell)
pwsh packages/cli/test/e2e-test.ps1
```
CI läuft automatisch bei Push/PR auf `main` über GitHub Actions und führt `e2e-test.sh` auf macOS und Ubuntu sowie `e2e-test.ps1` auf Windows aus.

## Lizenz

MIT