{"id":17603492,"url":"https://github.com/layr-labs/cerberus","last_synced_at":"2025-03-25T12:32:42.668Z","repository":{"id":259094455,"uuid":"874989641","full_name":"Layr-Labs/cerberus","owner":"Layr-Labs","description":"Go implementation of cerberus-api","archived":false,"fork":false,"pushed_at":"2025-03-10T16:23:00.000Z","size":169,"stargazers_count":6,"open_issues_count":6,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-17T05:37:05.691Z","etag":null,"topics":["bn254","cryptography"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Layr-Labs.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-18T21:05:22.000Z","updated_at":"2025-03-05T22:49:54.000Z","dependencies_parsed_at":"2025-01-13T23:27:29.697Z","dependency_job_id":"151026f0-c75f-4dd0-9f2d-ed7b27c3110a","html_url":"https://github.com/Layr-Labs/cerberus","commit_stats":null,"previous_names":["layr-labs/cerberus"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Layr-Labs%2Fcerberus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Layr-Labs%2Fcerberus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Layr-Labs%2Fcerberus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Layr-Labs%2Fcerberus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Layr-Labs","download_url":"https://codeload.github.com/Layr-Labs/cerberus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245462852,"owners_count":20619572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bn254","cryptography"],"created_at":"2024-10-22T13:59:30.858Z","updated_at":"2025-03-25T12:32:42.651Z","avatar_url":"https://github.com/Layr-Labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Remote Signer Implementation of cerberus-api\nThis is a remote signer which supports BLS signatures on the BN254 curve.\n\n## Disclaimer\n🚧 Cerberus is under active development and has not been audited. Cerberus is rapidly being upgraded, features may be added, removed or otherwise improved or modified and interfaces will have breaking changes. Cerberus should be used only for testing purposes and not in production. Cerberus is provided \"as is\" and Eigen Labs, Inc. does not guarantee its functionality or provide support for its use in production. 🚧\n\n\u003c!-- TOC --\u003e\n* [Remote Signer Implementation of cerberus-api](#remote-signer-implementation-of-cerberus-api)\n    * [Installation](#installation)\n      * [Quick start](#quick-start)\n      * [Manual](#manual)\n    * [Usage options](#usage-options)\n    * [Monitoring](#monitoring)\n    * [Configuring Server-side TLS (optional)](#configuring-server-side-tls-optional)\n      * [Generating TLS certificates](#generating-tls-certificates)\n      * [Starting the server with TLS support](#starting-the-server-with-tls-support)\n      * [Connecting a GO client with the server using TLS](#connecting-a-go-client-with-the-server-using-tls)\n    * [Migrating keys from eigenlayer-cli to cerberus](#migrating-keys-from-eigenlayer-cli-to-cerberus)\n  * [Security Bugs](#security-bugs)\n\u003c!-- TOC --\u003e\n\n### Installation\n#### Quick start\n```bash\n$ git clone https://github.com/Layr-Labs/cerberus.git\n$ cd cerberus\n$ make start\n```\n\n#### Manual\n```bash\ngit clone https://github.com/Layr-Labs/cerberus.git\ncd cerberus\ngo build -o bin/cerberus cmd/cerberus/main.go\n./bin/cerberus \n```\n\n### Usage options\n```bash\ncerberus --help\n        \n                   _                             \n                  | |                            \n  ___   ___  _ __ | |__    ___  _ __  _   _  ___ \n / __| / _ \\| '__|| '_ \\  / _ \\| '__|| | | |/ __|\n| (__ |  __/| |   | |_) ||  __/| |   | |_| |\\__ \\\n \\___| \\___||_|   |_.__/  \\___||_|    \\__,_||___/\n\n  \nNAME:\n   cerberus - Remote BLS Signer\n\nUSAGE:\n   cerberus [global options] command [command options]\n\nVERSION:\n   development\n\nCOMMANDS:\n   help, h  Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --admin-port value               Port for the admin server (default: 50052) [$ADMIN_PORT]\n   --aws-access-key-id value        AWS access key ID [$AWS_ACCESS_KEY_ID]\n   --aws-authentication-mode value  AWS authentication mode - supported modes: environment, specified (default: \"environment\") [$AWS_AUTHENTICATION_MODE]\n   --aws-profile value              AWS profile (default: \"default\") [$AWS_PROFILE]\n   --aws-region value               AWS region (default: \"us-east-2\") [$AWS_REGION]\n   --aws-secret-access-key value    AWS secret access key [$AWS_SECRET_ACCESS_KEY]\n   --enable-admin                   Enable the admin server (default: false) [$ENABLE_ADMIN]\n   --gcp-project-id value           Project ID for Google Cloud Platform [$GCP_PROJECT_ID]\n   --grpc-port value                Port for the gRPC server (default: 50051) [$GRPC_PORT]\n   --keystore-dir value             Directory where the keystore files are stored (default: \"./data/keystore\") [$KEYSTORE_DIR]\n   --log-format value               Log format - supported formats: text, json (default: \"text\") [$LOG_FORMAT]\n   --log-level value                Log level - supported levels: debug, info, warn, error (default: \"info\") [$LOG_LEVEL]\n   --metrics-port value             Port for the metrics server (default: 9091) [$METRICS_PORT]\n   --postgres-database-url value    Postgres database URL (default: \"postgres://user:password@localhost:5432/cerberus?sslmode=disable\") [$POSTGRES_DATABASE_URL]\n   --storage-type value             Storage type - supported types: filesystem, aws-secret-manager (default: \"filesystem\") [$STORAGE_TYPE]\n   --tls-ca-cert value              TLS CA certificate [$TLS_CA_CERT]\n   --tls-server-key value           TLS server key [$TLS_SERVER_KEY]\n   --help, -h                       show help\n   --version, -v                    print the version\n\nCOPYRIGHT:\n   (c) 2025 Eigen Labs\n```\n\n### Storage Backend\nWe support the following storage backends for storing private keys:\n1. [Filesystem](docs/filesystem.md)\n2. [AWS Secret Manager](docs/aws_sercret_manager.md)\n3. [Google Secret Manager](docs/google_secret_manager.md)\n\n### Monitoring\nThe signer exposes prometheus metrics on the `/metrics` endpoint. You can scrape these metrics using a prometheus server.\nThere is a grafana dashboard available in the `monitoring` directory. You can import this dashboard into your grafana server to monitor the signer.\n\n### Configuring Server-side TLS (optional)\n\nServer-side TLS support is provided to encrypt traffic between the client and server. This can be enabled by starting the service with `tls-ca-cert` and `tls-server-key` parameters set:\n\n#### Generating TLS certificates\n\nFor local testing purposes, the following commands can be used to generate a server certificate and key.\n\nCreate a file named `openssl.cnf` with the following content:\n\n```\n[ req ]\ndefault_bits       = 2048\ndefault_md         = sha256\ndefault_keyfile    = server.key\nprompt             = no\nencrypt_key        = no\n\ndistinguished_name = req_distinguished_name\nx509_extensions    = v3_req\n\n[ req_distinguished_name ]\nC            = US\nST           = California\nL            = San Francisco\nO            = My Company\nOU           = My Division\nCN           = localhost\n\n[ v3_req ]\nsubjectAltName = @alt_names\n\n[ alt_names ]\nDNS.1 = localhost\n```\n\n```bash\n# Generate the private key\nopenssl genpkey -algorithm RSA -out server.key\n\n# Generate the certificate signing request (CSR)\nopenssl req -new -key server.key -out server.csr -config openssl.cnf\n\n# Generate the self-signed certificate with SAN\nopenssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt -extensions v3_req -extfile openssl.cnf\n\n```\n\nserver.crt and server.key files can then be used to start the server with TLS support.\n\n#### Starting the server with TLS support\n\n```\ncerberus -tls-ca-cert server.crt -tls-server-key server.key\n```\n\nThe server can then be queried over a secure connection using a gRPC client that supports TLS. For example, using `grpcurl`:\n\n```\ngrpcurl -cacert server.crt -d '{\"password\": \"test\"}' -import-path . -proto proto/keymanager.proto localhost:50051 keymanager.v1.KeyManager/GenerateKeyPair\n```\n\n#### Connecting a GO client with the server using TLS\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n    \"time\"\n\n    \"github.com/Layr-Labs/cerberus-api/pkg/api/v1\"\n\n    \"google.golang.org/grpc\"\n    \"google.golang.org/grpc/credentials\"\n)\n\nconst SIGNER_API_KEY = \"\u003cAPI-KEY\u003e\"\n\nfunc main() {\n    creds, err := credentials.NewClientTLSFromFile(\"server.crt\", \"\")\n    if err != nil {\n        log.Fatalf(\"could not load tls cert: %s\", err)\n    }\n\n    conn, err := grpc.Dial(\"localhost:50051\", grpc.WithTransportCredentials(creds))\n    if err != nil {\n        log.Fatalf(\"did not connect: %v\", err)\n    }\n    defer conn.Close()\n\n    c := v1.NewSignerClient(conn)\n\n    ctx, cancel := context.WithTimeout(context.Background(), time.Second)\n    defer cancel()\n\n    req := \u0026v1.SignGenericRequest{\n        PublicKey: \"0xabcd\",\n        Password:  \"p@$$w0rd\",\n        Data:      []byte{0x01, 0x02, 0x03},\n    }\n\n    // Pass the API key to the signer client\n    ctx = metadata.AppendToOutgoingContext(ctx, \"authorization\", SIGNER_API_KEY)\n    resp, err := c.SignGeneric(ctx, req)\n    if err != nil {\n        log.Fatalf(\"could not sign: %v\", err)\n    }\n    fmt.Printf(\"Signature: %v\\n\", resp.Signature)\n}\n```\n\n### Migrating keys from eigenlayer-cli to cerberus\nIf you created your keys using the eigenlayer-cli,\nyou won't be able to directly copy the encrypted json file as this keystore uses ERC2335 format (eigenlayer-cli will add support for this soon).\n\nYou can migrate them to cerberus using the following steps:\n1. Export your keys from eigenlayer-cli\n    ```bash\n    eigenlayer keys export --key-type bls \u003ckey-name\u003e\n    ```\n2. Copy the private key from the output.\n3. Import the key into cerberus\n    ```bash\n    grpcurl -plaintext -d '{\"privateKey\": \"\u003cpk\u003e\", \"password\": \"p@$$w0rd\"}' \u003cip\u003e:\u003cport\u003e keymanager.v1.KeyManager/ImportKey\n    ```\n\n## Security Bugs\nPlease report security vulnerabilities to security@eigenlabs.org. Do NOT report security bugs via Github Issues.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayr-labs%2Fcerberus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flayr-labs%2Fcerberus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayr-labs%2Fcerberus/lists"}