{"id":27384263,"url":"https://github.com/valera-rozuvan/gen2fa","last_synced_at":"2025-10-16T10:11:21.316Z","repository":{"id":150501449,"uuid":"449570491","full_name":"valera-rozuvan/gen2fa","owner":"valera-rozuvan","description":"generate 2FA codes helper utility","archived":false,"fork":false,"pushed_at":"2024-02-18T21:42:03.000Z","size":1279,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-10T13:38:06.601Z","etag":null,"topics":["2fa","2fa-security","security"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/valera-rozuvan.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,"zenodo":null}},"created_at":"2022-01-19T06:16:13.000Z","updated_at":"2023-03-04T03:26:13.000Z","dependencies_parsed_at":"2024-02-18T22:42:48.991Z","dependency_job_id":null,"html_url":"https://github.com/valera-rozuvan/gen2fa","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/valera-rozuvan/gen2fa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valera-rozuvan%2Fgen2fa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valera-rozuvan%2Fgen2fa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valera-rozuvan%2Fgen2fa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valera-rozuvan%2Fgen2fa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valera-rozuvan","download_url":"https://codeload.github.com/valera-rozuvan/gen2fa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valera-rozuvan%2Fgen2fa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279176564,"owners_count":26119737,"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","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["2fa","2fa-security","security"],"created_at":"2025-04-13T16:24:33.273Z","updated_at":"2025-10-16T10:11:21.268Z","avatar_url":"https://github.com/valera-rozuvan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gen2fa\n\ngenerate 2FA codes helper utility\n\n![gen2fa video preview](./video_preview/gen2fa-sample.gif)\n\n## About\n\nWe want to use [pass](https://www.passwordstore.org/) to securely store 2FA secrets, and [onetimepass](https://pypi.org/project/onetimepass/) to generate the 2FA codes. We want a nice Bash script to tie the two together. This will:\n\n- allow for automation\n- provide a fast workflow for generating 2FA codes for any service which requires 2FA\n\n## Rationale\n\nWhy did I create the `gen2fa` helper utility? Because pulling out my mobile phone every time I needed a 2FA code got deeply frustrating. Also, because I needed to automate some CI workflows, which required manual intervention by the operator (inserting a 2FA code generated by a mobile phone).\n\n## Requirements\n\n- [pass](https://www.passwordstore.org/)\n- [Python](https://www.python.org/) v3.3+\n- [Bash](https://www.gnu.org/software/bash/)\n- [grep](https://www.gnu.org/software/grep/)\n- [xclip](https://github.com/astrand/xclip)\n- [sed](https://www.gnu.org/software/sed/)\n\nThe Python module [onetimepass](https://pypi.org/project/onetimepass/) is provided in this source tree. This is because we need [a fix](https://github.com/tadeck/onetimepass/pull/22), which has not been merged into the original project for a long time (still the case as of `08.01.2024`).\n\n## How this works\n\nFundamentally, you need two things. First, is an entry in pass called `two_fa`. For example, running:\n\n```shell\n$ pass two_fa\n```\n\nshould produce:\n\n```text\nacc1: provider1/user_name\nacc2 name: provider2/other_username\nacc3: provider3\n```\n\n`gen2fa` utility will parse this output and will interpret everything up to the semicolon (`:`) as the account name. What comes after, is the pass entry for that account. It should contain the 2FA secret.\n\nSecond, you need 2FA secrets stored in pass under each account entry. For example, running:\n\n```shell\n$ pass provider2/other_username\n```\n\nshould produce:\n\n```text\n... some stuff\n2FA secret: UDHFJH6756HJGKJF786KJGFDGH675KHGHG\n... some more stuff\n```\n\n`gen2fa` utility will parse this output, and will extract the 2FA secret from the line that starts with `2FA secret: `.\n\n## Usage\n\nFor the standard case when you just need to get a 2FA code, and login to some website:\n\n```shell\n$ gen2fa -c\nEnter the account to generate 2FA: acc2 name\n\n2FA code '123456' was copied to clipboard. Will clear in 6 seconds...\n```\n\nIf you need to get a 2FA code as part of some automation script, you can use:\n\n```shell\n$ TWO_FA_CODE=$(gen2fa -q \u003c\u003c\u003c \"acc2 name\")\n$ echo $TWO_FA_CODE\n123456\n```\n\n![gen2fa automation video preview](./video_preview/gen2fa-sample-2.gif)\n\nNOTE: If, for automation purposes, you want to skip GnuPG asking for a passphrase - you can setup GnuPG to keep credentials cached for a really long time. You just enter the passphrase one time, and forget about it. See `default-cache-ttl` and `max-cache-ttl` configuration options in [GnuPG docs](https://www.gnupg.org/documentation/manuals/gnupg/Agent-Options.html). Set both `ttl` options to a year or so (say, 34560000 seconds, which is around 400 days), and you should be fine.\n\n## Optional arguments\n\nAvailable CLI arguments, understood by the script:\n\n```text\n  -l | --list       List available accounts to generate 2FA for.\n  -c | --clipboard  Copy the 2FA code to clipboard using xclip.\n  -q | --quiet      Try to be less verbose.\n  -d | --debug      Print extra debugging information - contents of the script variables.\n  -h | --help       Print help information; CLI usage.\n       --version    Print version.\n```\n\n## Useful alias\n\nTo be able to run `gen2fa` using just the script name, you can add an alias to your `.bashrc`:\n\n```shell\nalias gen2fa=\"/home/user/path/to/project/gen2fa/gen2fa.sh\"\n```\n\nReload your `.bashrc` (one way is to close \u0026 open your terminal). Then you can do:\n\n```shell\n$ gen2fa --version\ngen2fa v1.1\n```\n\n## Security implications\n\nSome thoughts on security behind 2FA, and the approach taken by the `gen2fa` utility.\n\nWhen you enable 2FA on some site (or for some service), you will use something like [Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator) to scan a bar code, and then enter a newly generated 2FA code to proceed. Most likely the site (or service) will also give you several 2FA backup codes to be used in case of emergencies. Some scenarios when you would need the 2FA backup codes:\n\n- you lost the phone with the authenticator app\n- the phone got damaged (can't repair)\n\nIn an ideal world, you will print the backup codes on paper, and stash the paper in a safe place. If you lose your 2FA device, you have 2FA backup codes on paper, and can recover access to your account.\n\nThe safest way to protect your accounts is to store the different kinds of login credentials separately. Passwords should be stored in one secure place, 2FA secrets (along with ability to generate 2FA codes) in another secure place, and 2FA backup codes in a third secure place. This way, even if one of the secret storage places gets compromised, the attacker has only partial login credentials, and can't access your account.\n\nIn a less ideal world, what happens most of the time, you save everything (including the 2FA backup codes) in some password manager. The author of `gen2fa` is using [pass](https://www.passwordstore.org/) to store the 2FA backup codes. When using pass, everything is encrypted using your private [GPG](https://gnupg.org/) key. If the pass store is compromised, then the backup codes are revealed, and the adversary receives access to your accounts. However, if you follow sane security guidelines, it is very unlikely that someone will compromise your pass store. First, your GPG private key has to be compromised. Second, your pass store has to be compromised.\n\nIn any case, if you are already storing everything in a pass store, storing the 2FA secret along does not weaken the security of your accounts.\n\nNOTE! For highly critical production systems, care needs to be taken when dealing with security matters. In such cases, the author of `gen2fa` recommends storing different types of login credentials separately. Therefore, the author of `gen2fa` does not advocate the use of `gen2fa` for critical production system accounts.\n\n---\n\n## license\n\nThe project `'gen2fa'` is licensed under the MIT License.\n\nSee [LICENSE](./LICENSE) for more details.\n\nThe latest source code can be retrieved from one of several mirrors:\n\n1. [github.com/valera-rozuvan/gen2fa](https://github.com/valera-rozuvan/gen2fa)\n\n2. [gitlab.com/valera-rozuvan/gen2fa](https://gitlab.com/valera-rozuvan/gen2fa)\n\n3. [git.rozuvan.net/gen2fa](https://git.rozuvan.net/gen2fa)\n\nCopyright (c) 2022-2024 [Valera Rozuvan](https://valera.rozuvan.net/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalera-rozuvan%2Fgen2fa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalera-rozuvan%2Fgen2fa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalera-rozuvan%2Fgen2fa/lists"}