{"id":13550912,"url":"https://github.com/nanopack/shaman","last_synced_at":"2026-02-14T14:14:36.840Z","repository":{"id":57493933,"uuid":"45634477","full_name":"nanopack/shaman","owner":"nanopack","description":"Small, lightweight, api-driven dns server.","archived":false,"fork":false,"pushed_at":"2020-04-29T16:51:45.000Z","size":123,"stargazers_count":455,"open_issues_count":9,"forks_count":34,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-03T01:33:52.252Z","etag":null,"topics":["clustering","developer-tools","devops","devtools","dns","dns-server","golang","nanobox","nanopack"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nanopack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-05T19:33:18.000Z","updated_at":"2025-03-18T23:25:58.000Z","dependencies_parsed_at":"2022-09-02T01:40:31.995Z","dependency_job_id":null,"html_url":"https://github.com/nanopack/shaman","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nanopack/shaman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanopack%2Fshaman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanopack%2Fshaman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanopack%2Fshaman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanopack%2Fshaman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nanopack","download_url":"https://codeload.github.com/nanopack/shaman/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanopack%2Fshaman/sbom","scorecard":{"id":674070,"data":{"date":"2025-08-11","repo":{"name":"github.com/nanopack/shaman","commit":"bc3bb04be051f1802781d7b27e84893ff1b949ba"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.7,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":5,"reason":"Found 4/7 approved changesets -- score normalized to 5","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v0.0.4 not signed: https://api.github.com/repos/nanopack/shaman/releases/3917978","Warn: release artifact v0.0.3 not signed: https://api.github.com/repos/nanopack/shaman/releases/3221715","Warn: release artifact v0.0.4 does not have provenance: https://api.github.com/repos/nanopack/shaman/releases/3917978","Warn: release artifact v0.0.3 does not have provenance: https://api.github.com/repos/nanopack/shaman/releases/3221715"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 29 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-21T21:00:12.185Z","repository_id":57493933,"created_at":"2025-08-21T21:00:12.185Z","updated_at":"2025-08-21T21:00:12.185Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29446653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T14:10:32.461Z","status":"ssl_error","status_checked_at":"2026-02-14T14:09:49.945Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clustering","developer-tools","devops","devtools","dns","dns-server","golang","nanobox","nanopack"],"created_at":"2024-08-01T12:01:39.393Z","updated_at":"2026-02-14T14:14:36.824Z","avatar_url":"https://github.com/nanopack.png","language":"Go","funding_links":[],"categories":["Go","Capabilities","golang","Packages"],"sub_categories":["Configuration \u0026 Discovery","Unsorted"],"readme":"[![shaman logo](http://nano-assets.gopagoda.io/readme-headers/shaman.png)](http://nanobox.io/open-source#shaman)  \n[![Build Status](https://travis-ci.org/nanopack/shaman.svg)](https://travis-ci.org/nanopack/shaman)\n[![GoDoc](https://godoc.org/github.com/nanopack/shaman?status.svg)](https://godoc.org/github.com/nanopack/shaman)\n[![Go Report Card](https://goreportcard.com/badge/github.com/nanopack/shaman)](https://goreportcard.com/report/github.com/nanopack/shaman)\n\u003c!-- [![GoCover](https://gocover.io/_badge/github.com/nanopack/shaman)](https://gocover.io/github.com/nanopack/shaman) --\u003e\n\n# Shaman\n\nSmall, clusterable, lightweight, api-driven dns server.\n\n\n## Quickstart:\n```sh\n# Start shaman with defaults (requires admin privileges (port 53))\nshaman -s\n\n# register a new domain\nshaman add -d nanopack.io -A 127.0.0.1\n\n# perform dns lookup\n# OR `nslookup -port=53 nanopack.io 127.0.0.1`\ndig @localhost nanopack.io +short\n# 127.0.0.1\n\n# Congratulations!\n```\n\n\n## Usage:\n\n### As a CLI\nSimply run `shaman \u003cCOMMAND\u003e`\n\n`shaman` or `shaman -h` will show usage and a list of commands:\n\n```\nshaman - api driven dns server\n\nUsage:\n  shaman [flags]\n  shaman [command]\n\nAvailable Commands:\n  add         Add a domain to shaman\n  delete      Remove a domain from shaman\n  list        List all domains in shaman\n  get         Get records for a domain\n  update      Update records for a domain\n  reset       Reset all domains in shaman\n\nFlags:\n  -C, --api-crt string            Path to SSL crt for API access\n  -a, --api-domain string         Domain of generated cert (if none passed) (default \"shaman.nanobox.io\")\n  -k, --api-key string            Path to SSL key for API access\n  -p, --api-key-password string   Password for SSL key\n  -H, --api-listen string         Listen address for the API (ip:port) (default \"127.0.0.1:1632\")\n  -c, --config-file string        Configuration file to load\n  -O, --dns-listen string         Listen address for DNS requests (ip:port) (default \"127.0.0.1:53\")\n  -d, --domain string             Parent domain for requests (default \".\")\n  -f, --fallback-dns              Fallback dns server address (ip:port), if not specified fallback is not used\n  -i, --insecure                  Disable tls key checking (client) and listen on http (api). Also disables auth-token\n  -2, --l2-connect string         Connection string for the l2 cache (default \"scribble:///var/db/shaman\")\n  -l, --log-level string          Log level to output [fatal|error|info|debug|trace] (default \"INFO\")\n  -s, --server                    Run in server mode\n  -t, --token string              Token for API Access (default \"secret\")\n  -T, --ttl int                   Default TTL for DNS records (default 60)\n  -v, --version                   Print version info and exit\n\nUse \"shaman [command] --help\" for more information about a command.\n```\n\nFor usage examples, see [api](api/README.md) and/or [cli](commands/README.md) readme  \n\n### As a Server\nTo start shaman as a server run:  \n`shaman --server`  \nAn optional config file can also be passed on startup:  \n`shaman -c config.json`  \n\n\u003econfig.json\n\u003e```json\n\u003e{\n\u003e  \"api-domain\": \"shaman.nanobox.io\",\n\u003e  \"api-crt\": \"\",\n\u003e  \"api-key\": \"\",\n\u003e  \"api-key-password\": \"\",\n\u003e  \"api-listen\": \"127.0.0.1:1632\",\n\u003e  \"token\": \"secret\",\n\u003e  \"insecure\": false,\n\u003e  \"l2-connect\": \"scribble:///var/db/shaman\",\n\u003e  \"ttl\": 60,\n\u003e  \"domain\": \".\",\n\u003e  \"dns-listen\": \"127.0.0.1:53\",\n\u003e  \"log-level\": \"info\",\n\u003e  \"server\": true\n\u003e}\n\u003e```\n\n#### L2 connection strings\n\n##### Scribble Cacher\nThe connection string looks like `scribble://localhost/path/to/data/store`.\n\n\u003c!--\n#### Redis Cacher\nThe connection string looks like `redis://[user:password@]host:port/`.\n\n#### Postgresql Cacher\nThe connection string looks like `postgres://[user@]host/database`.\n --\u003e\n\n\n## API:\n\n| Route | Description | Payload | Output |\n| --- | --- | --- | --- |\n| **POST** /records | Adds the domain and full record | json domain object | json domain object |\n| **PUT** /records | Update all domains and records (replaces all) | json array of domain objects | json array of domain objects |\n| **GET** /records | Returns a list of domains we have records for | nil | string array of domains |\n| **PUT** /records/{domain} | Update domain's records (replaces all) | json domain object | json domain object |\n| **GET** /records/{domain} | Returns the records for that domain | nil | json domain object |\n| **DELETE** /records/{domain} | Delete a domain | nil | success message |\n\n**note:** The API requires a token to be passed for authentication by default and is configurable at server start (`--token`). The token is passed in as a custom header: `X-AUTH-TOKEN`.  \n\nFor examples, see [the api's readme](api/README.md)  \n\n\n## Overview\n\n```sh\n+------------+     +----------+     +-----------------+\n|            +-----\u003e          +-----\u003e                 |\n| API Server |     |          |     |   Short-Term    |\n|            \u003c-----+ Caching  \u003c-----+   (in-memory)   |\n+------------+     | And      |     +-----------------+\n                   | Database |\n+------------+     | Manager  |     +-----------------+\n|            +-----\u003e          +-----\u003e                 |\n| DNS Server |     |          |     | Long-Term (L2)  |\n|            \u003c-----+          \u003c-----+                 |\n+------------+     +----------+     +-----------------+\n```\n\n\n## Data types:\n### Domain (Resource):\njson:\n```json\n{\n  \"domain\": \"nanopack.io.\",\n  \"records\": [\n    {\n      \"ttl\": 60,\n      \"class\": \"IN\",\n      \"type\": \"A\",\n      \"address\": \"127.0.0.1\"\n    },\n    {\n      \"ttl\": 60,\n      \"class\": \"IN\",\n      \"type\": \"A\",\n      \"address\": \"127.0.0.2\"\n    }\n  ]\n}\n```\n\nFields:\n- **domain**: Domain name to resolve\n- **records**: Array of address records\n  - **ttl**: Seconds a client should cache for\n  - **class**: Record class\n  - **type**: Record type\n    - A - Address record\n    - CNAME - Canonical name record\n    - MX - Mail exchange record\n    - [Many more](https://en.wikipedia.org/wiki/List_of_DNS_record_types) - may or may not work as is\n  - **address**: Address domain resolves to\n    - \u003csup\u003enote: Special rules apply in some cases. E.g. MX records require a number \"10 mail.google.com\"\u003c/sup\u003e\n\n### Error:\njson:\n```json\n{\n  \"err\": \"exit status 2: unexpected argument\"\n}\n```\n\nFields:\n - **err**: Error message\n\n### Message:\njson:\n```json\n{\n  \"msg\": \"Success\"\n}\n```\n\nFields:\n - **msg**: Success message\n\n\n## Todo\n- atomic local cache updates\n- export in hosts file format\n- improve scribble add (adding before stored in cache overwrites)\n\n\n## Changelog\n- v0.0.2 (May 11, 2016)\n  - Refactor to allow multiple records per domain and more fully utilize dns library\n- v0.0.3 (May 12, 2016)\n  - Tests for DNS server\n  - Start Server Insecure\n- v0.0.4 (Aug 16, 2016)\n  - Postgresql as a backend\n\n\n## Contributing\nContributions to shaman are welcome and encouraged. Shaman is a [Nanobox](https://nanobox.io) project and contributions should follow the [Nanobox Contribution Process \u0026 Guidelines](https://docs.nanobox.io/contributing/).\n\n\n[![oss logo](http://nano-assets.gopagoda.io/open-src/nanobox-open-src.png)](http://nanobox.io/open-source)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanopack%2Fshaman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnanopack%2Fshaman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanopack%2Fshaman/lists"}