Add Duo Push auto-approval and HOTP hex conversion

Implements three-priority Duo MFA authentication system:
1. OTP (highest priority) - Auto-generates HOTP codes from secret
2. Auto-approval - Uses device credentials to approve pushes via Duo API
3. Manual push (fallback) - Traditional approve-on-phone flow

Database changes:
- Add duo_push_akey, duo_push_pkey, duo_push_host, duo_push_rsa_key_path columns
- Add duo_device column to persist user's selected device
- Migration: 20522d39dc63_add_duo_push_method

Duo Push auto-approval:
- Integrate with Duo device API using RSA-SHA512 signed requests
- Load device credentials from database and RSA key from file
- Poll for pending push notifications and auto-approve
- Hard fail if auto-approval is configured but broken (prevents hanging)
- Auto-correct duo_device when credentials don't match selected device

HOTP hex secret auto-conversion:
- Auto-detect 32-char hex format (from synackDUO's hotp_secret)
- Convert by treating hex string as UTF-8, then base32 encode
- Based on duo-hotp reference implementation
- Accepts both hex (hotp_secret) and base32 (otpauth://) formats

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Derb237

docs/src/usage/index.md

@@ -17,12 +17,8 @@ With that in mind, I would highly recommend you become familiar with the [Plugin
 ## Authentication
 
 The first time you try to do anything which requires authentication, you will be automatically prompted for your credentials.
-This prompt will expect the `Synack Email` and `Synack Password`, which are fairly self explanitory, but it also asks for the `Synack OTP Secret`.
+This prompt will expect the `Synack Email` and `Synack Password`, which are fairly self explanatory.
 
-The `Synack OTP Secret` is NOT the 8 digit code you pull out of Authy.
-Instead, it is a string that you must extract from Authy via a method similar to the one found [here](https://gist.github.com/gboudreau/94bb0c11a6209c82418d01a59d958c93).
-
-Use the above instructions at your own discression.
-I TAKE NO RESPONSIBILITY IF SOMETHING BAD HAPPENS AS A RESULT.
+For Duo MFA setup options, see the [Duo plugin documentation](./plugins/duo.md).
 
 Once you complete these steps, your credentials are stored in a SQLiteDB at `~/.config/synack/synackapi.db`.

docs/src/usage/main-components/state.md

@@ -55,12 +55,16 @@ In the event that one of the State variables is set and is **not** constantly at
 | api_token | str | This is the Synack Access Token used to authenticate requests
 | config_dir | pathlib.Path | The location of the Database and Login script
 | debug | bool | Used to show/hide debugging messages
+| duo_push_akey | str | Duo device activation key for push auto-approval
+| duo_push_host | str | Duo API hostname for push auto-approval
+| duo_push_pkey | str | Duo device private key for push auto-approval
+| duo_push_rsa_key_path | str | Path to RSA private key for signing Duo API requests
 | email | str | Your email address used to log into Synack
 | http_proxy | str | A Web Proxy (Burp, etc.) to intercept requests
 | https_proxy | str | A Web Proxy (Burp, etc.) to intercept requests
 | login | bool | Used to enable/disable a check of the api_token upon creation of the Handler
 | notifications_token | str | Token used for authentication when dealing with Synack Notifications
-| otp_secret | str | OTP Secret held by Authy. NOT an OTP. For more information, read the Usage page
+| otp_secret | str | OTP Secret held by Duo Mobile. NOT an OTP. For more information, read the Usage page
 | password | str | Your Synack Password
 | session | requests.Session | Tracks cookies and headers across various functions
 | template_dir | pathlib.Path | The location of your Mission Templates

docs/src/usage/plugins/duo.md

@@ -1,5 +1,58 @@
 # Duo
 
+## Duo MFA Options
+
+When prompted during authentication, you can choose from three options:
+
+**Option 1: Manual Push Approval (Simplest)**
+- Press Enter when prompted for OTP Secret
+- Approve push notifications on your phone each time the token is expired
+- No additional setup required
+
+**Option 2: Automated OTP (Preferred)**
+- Enter your OTP Secret when prompted (accepts both hex and base32 formats)
+- Automatically generates OTP codes using a counter (saved in the database)
+- Extract the `hotp_secret` from Duo Mobile using [synackDUO](https://github.com/dinosn/synackDUO) (see `response.json`)
+- **Note:** This is NOT the 8-digit codes from Duo Mobile, but the HOTP secret key
+
+**Option 3: Automated Duo Push**
+- Uses Duo credentials to auto-approve push requests
+- Can also approve push requests using duo.approve_pending_push(timeout)
+- Extract credentials using [synackDUO](https://github.com/dinosn/synackDUO) (see `response.json`) (see below)
+
+
+**Disclaimer:** Use the above instructions at your own discretion. I TAKE NO RESPONSIBILITY IF SOMETHING BAD HAPPENS AS A RESULT.
+
+## Duo Push Auto-Approval Setup
+
+The Duo plugin supports push notification approval using device credentials.
+
+### Prerequisites
+
+You must extract and configure four credentials from Duo Mobile:
+
+| Credential | Description | Example
+| --- | --- | ---
+| `duo_push_akey` | Device activation key | `DAXXXXXXXXXXXXXXXXXXXX`
+| `duo_push_pkey` | Device private key | `DPXXXXXXXXXXXXXXXXXXXX`
+| `duo_push_host` | Duo API hostname | `api-xxxxxxxx.duosecurity.com`
+| `duo_push_rsa_key_path` | Path to RSA private key | `~/.config/synack/duo/key.pem`
+
+### Configuration
+
+Set credentials in the database:
+PP
+```python
+import synack
+
+h = synack.Handler(login=False)
+
+h.db.set_config('duo_push_akey', 'DAXXXXXXXXXXXXXXXXXX')
+h.db.set_config('duo_push_pkey', 'DPXXXXXXXXXXXXXXXXXX')
+h.db.set_config('duo_push_host', 'api-xxxxxxxx.duosecurity.com')
+h.db.set_config('duo_push_rsa_key_path', 'synackDUO/key.pem')
+```
+
 ## duo.get_grant_token(auth_url)
 
 > Handles Duo Security MFA stages and returns the grant_token used to finish logging into Synack
@@ -13,3 +66,21 @@
 >> >>> h.duo.get_grant_token('https:///...duosecurity.com/...')
 >> 'Y8....6g'
 >> ```
+
+## duo.approve_pending_push(timeout)
+
+> Wait for and approve a single Duo push notification
+>
+> Polls Duo's device API for pending push notifications and automatically approves the first one found. Useful for automated workflows that need to handle Duo MFA.
+>
+> | Argument | Type | Default | Description
+> | --- | --- | --- | ---
+> | `timeout` | int | 30 | Maximum seconds to wait for a push notification
+>
+> Returns `True` if a push was approved, `False` if timeout or error occurred.
+>
+>> Examples
+>> ```python3
+>> >>> h.duo.approve_pending_push(timeout=60)
+>> True
+>> ```

src/synack/_state.py

@@ -41,6 +41,11 @@ def __init__(self):
         self._use_proxies = None
         self._use_scratchspace = None
         self._user_id = None
+        self._duo_push_akey = None
+        self._duo_push_pkey = None
+        self._duo_push_host = None
+        self._duo_push_rsa_key_path = None
+        self._duo_device = None
 
     @property
     def smtp_email_from(self) -> str:
@@ -357,3 +362,58 @@ def user_id(self) -> str:
     @user_id.setter
     def user_id(self, value: str) -> None:
         self._user_id = value
+
+    @property
+    def duo_push_akey(self) -> str:
+        ret = self._duo_push_akey
+        if ret is None:
+            ret = self._db.duo_push_akey
+        return ret
+
+    @duo_push_akey.setter
+    def duo_push_akey(self, value: str) -> None:
+        self._duo_push_akey = value
+
+    @property
+    def duo_push_pkey(self) -> str:
+        ret = self._duo_push_pkey
+        if ret is None:
+            ret = self._db.duo_push_pkey
+        return ret
+
+    @duo_push_pkey.setter
+    def duo_push_pkey(self, value: str) -> None:
+        self._duo_push_pkey = value
+
+    @property
+    def duo_push_host(self) -> str:
+        ret = self._duo_push_host
+        if ret is None:
+            ret = self._db.duo_push_host
+        return ret
+
+    @duo_push_host.setter
+    def duo_push_host(self, value: str) -> None:
+        self._duo_push_host = value
+
+    @property
+    def duo_push_rsa_key_path(self) -> str:
+        ret = self._duo_push_rsa_key_path
+        if ret is None:
+            ret = self._db.duo_push_rsa_key_path
+        return ret
+
+    @duo_push_rsa_key_path.setter
+    def duo_push_rsa_key_path(self, value: str) -> None:
+        self._duo_push_rsa_key_path = value
+
+    @property
+    def duo_device(self) -> str:
+        ret = self._duo_device
+        if ret is None:
+            ret = self._db.duo_device
+        return ret
+
+    @duo_device.setter
+    def duo_device(self, value: str) -> None:
+        self._duo_device = value

src/synack/db/alembic/versions/20522d39dc63_add_duo_push_method.py

@@ -0,0 +1,36 @@
+"""add_duo_push_method
+
+Revision ID: 20522d39dc63
+Revises: 8b478a84c1a6
+Create Date: 2025-11-06 06:45:20.877380
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '20522d39dc63'
+down_revision = '8b478a84c1a6'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('config', sa.Column('duo_device', sa.VARCHAR(length=50), nullable=True))
+    op.add_column('config', sa.Column('duo_push_akey', sa.VARCHAR(length=200), nullable=True))
+    op.add_column('config', sa.Column('duo_push_host', sa.VARCHAR(length=100), nullable=True))
+    op.add_column('config', sa.Column('duo_push_pkey', sa.VARCHAR(length=200), nullable=True))
+    op.add_column('config', sa.Column('duo_push_rsa_key_path', sa.VARCHAR(length=250), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('config', 'duo_push_rsa_key_path')
+    op.drop_column('config', 'duo_push_pkey')
+    op.drop_column('config', 'duo_push_host')
+    op.drop_column('config', 'duo_push_akey')
+    op.drop_column('config', 'duo_device')
+    # ### end Alembic commands ###

src/synack/db/models/config.py

@@ -38,3 +38,10 @@ class Config(Base):
     user_id = sa.Column(sa.VARCHAR(20), default='')
     use_proxies = sa.Column(sa.BOOLEAN, default=False)
     use_scratchspace = sa.Column(sa.BOOLEAN, default=False)
+    duo_push_akey = sa.Column(sa.VARCHAR(200), default='')
+    duo_push_pkey = sa.Column(sa.VARCHAR(200), default='')
+    duo_push_host = sa.Column(sa.VARCHAR(100), default='')
+    duo_push_rsa_key_path = sa.Column(
+        sa.VARCHAR(250), default=''
+    )
+    duo_device = sa.Column(sa.VARCHAR(50), default='')

src/synack/plugins/db.py

@@ -497,14 +497,49 @@ def otp_count(self, value):
     def otp_secret(self):
         ret = self.get_config('otp_secret')
         if not ret:
-            ret = input('Synack OTP Secret: ')
-            self.otp_secret = ret
+            # Skip prompt if automated push credentials are already configured
+            if self.duo_push_akey and self.duo_push_pkey and self.duo_push_host:
+                ret = ''
+                self.otp_secret = ret
+            # Skip prompt if user has already selected a device for manual push
+            elif self.duo_device:
+                ret = ''
+            else:
+                print("\nDuo MFA Authentication Setup:")
+                print(
+                    "1. Press Enter to use Duo Push notifications "
+                    "(you'll approve on your phone)"
+                )
+                print("2. OR enter your Duo OTP Secret for automated passcode generation")
+                print("   (Accepts hex (hotp_secret) or base32 (otpauth://) format)")
+                ret = input('\nDuo OTP Secret (or press Enter for push): ').strip()
+                self.otp_secret = ret if ret else ''
         return ret
 
     @otp_secret.setter
     def otp_secret(self, value):
+        # Auto-detect and convert hex format to base32
+        # Duo's hotp_secret is a hex string, but needs to be treated as UTF-8
+        # not as hex bytes (based on duo-hotp reference implementation)
+        if value and self._is_hex_secret(value):
+            import base64
+            # Encode the hex string as UTF-8 bytes, then base32
+            value = base64.b32encode(value.encode('utf-8')).decode('ascii').rstrip('=')
         self.set_config('otp_secret', value)
 
+    def _is_hex_secret(self, value):
+        """Check if the secret appears to be in hex format (not base32)"""
+        # Hex: 32 chars using only 0-9, a-f
+        # Base32: variable length using A-Z, 2-7
+        if len(value) != 32:
+            return False
+        try:
+            # If it can be decoded as hex, it's hex
+            bytes.fromhex(value)
+            return True
+        except ValueError:
+            return False
+
     @property
     def password(self):
         ret = self.get_config('password')
@@ -517,6 +552,46 @@ def password(self):
     def password(self, value):
         self.set_config('password', value)
 
+    @property
+    def duo_push_akey(self):
+        return self.get_config('duo_push_akey')
+
+    @duo_push_akey.setter
+    def duo_push_akey(self, value):
+        self.set_config('duo_push_akey', value)
+
+    @property
+    def duo_push_pkey(self):
+        return self.get_config('duo_push_pkey')
+
+    @duo_push_pkey.setter
+    def duo_push_pkey(self, value):
+        self.set_config('duo_push_pkey', value)
+
+    @property
+    def duo_push_host(self):
+        return self.get_config('duo_push_host')
+
+    @duo_push_host.setter
+    def duo_push_host(self, value):
+        self.set_config('duo_push_host', value)
+
+    @property
+    def duo_push_rsa_key_path(self):
+        return self.get_config('duo_push_rsa_key_path')
+
+    @duo_push_rsa_key_path.setter
+    def duo_push_rsa_key_path(self, value):
+        self.set_config('duo_push_rsa_key_path', value)
+
+    @property
+    def duo_device(self):
+        return self.get_config('duo_device')
+
+    @duo_device.setter
+    def duo_device(self, value):
+        self.set_config('duo_device', value)
+
     @property
     def ports(self):
         session = self.Session()