{"id":26755125,"url":"https://github.com/cpscript/nfcman","last_synced_at":"2025-04-15T02:31:20.622Z","repository":{"id":282300750,"uuid":"875212272","full_name":"CPScript/NFCman","owner":"CPScript","description":"NFCman (NFC manipulator); Read, save, and emulate NFC cards on Android devices using Termux. By leveraging Host Card Emulation (HCE), it facilitates interaction with NFC readers for applications like access control and data sharing.","archived":false,"fork":false,"pushed_at":"2025-04-14T13:47:43.000Z","size":70,"stargazers_count":10,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-14T14:55:21.223Z","etag":null,"topics":["access-control","android","bash","card-emulation","data-management","hce","nfc","not-tested","open-source","python","termux"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CPScript.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-19T11:43:00.000Z","updated_at":"2025-04-14T13:47:46.000Z","dependencies_parsed_at":"2025-03-20T18:28:46.395Z","dependency_job_id":null,"html_url":"https://github.com/CPScript/NFCman","commit_stats":null,"previous_names":["cpscript/nfc-manipulation","cpscript/nfcman"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FNFCman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FNFCman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FNFCman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FNFCman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CPScript","download_url":"https://codeload.github.com/CPScript/NFCman/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248993889,"owners_count":21195275,"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":["access-control","android","bash","card-emulation","data-management","hce","nfc","not-tested","open-source","python","termux"],"created_at":"2025-03-28T14:18:24.434Z","updated_at":"2025-04-15T02:31:20.028Z","avatar_url":"https://github.com/CPScript.png","language":"Shell","readme":"## I would love for people to help out and contribute on this project. Pull requests are accepted.\n---\n\nNFCman lets you manipulate NFC cards and signals directly from your phone. With this tool, you can:\n- Read and extract data from NFC cards\n- Save card data for later use\n- Emulate cards to unlock doors, access control systems, and other NFC readers\n- Analyze card structures including MIFARE sectors\n- Customize card responses for specialized systems\n\n## Requirements\n\n- Android device with NFC capability\n- Termux installed\n- Android 4.4+ (KitKat) for HCE support\n- Python with nfcpy library\n\n## Installation\n\n1. Install Termux from Google Play or F-Droid\n\n2. Open Termux and install required packages:\n```bash\npkg update \u0026\u0026 pkg upgrade -y\npkg install git python termux-api jq -y\npip install nfcpy\n```\n\n3. Clone the repository:\n```bash\ngit clone https://github.com/CPScript/NFCman.git\ncd NFCman\n```\n\n4. Run the installer:\n```bash\nchmod +x install.sh\n./install.sh\n```\n\n5. Install the Android component:\n   - The installer will attempt to build and install the app\n   - If that fails, you'll need to manually build and install the APK\n\n## Project Structure\n\n```\nNFCman/\n├── android/                # Android HCE app files\n│   ├── AndroidManifest.xml # App configuration\n│   ├── NfcEmulatorService.java # Card emulation service\n│   └── res/xml/apduservice.xml # NFC service config\n├── config.json            # Framework configuration\n├── install.sh             # Installation script\n├── nfc_manager.sh         # Main interface script\n└── scripts/               # Utility scripts\n    ├── read_card.py       # Card reading script\n    ├── emulate_card.sh    # Card emulation script\n    ├── utils.py           # Python utilities\n    └── card_utils.sh      # Bash utilities\n```\n\n## Tutorial\n\n### 1. Reading an NFC Card\n\n1. Start the NFC manager:\n```bash\n./nfc_manager.sh\n```\n\n2. Select option `1` (Read NFC Card) from the menu.\n\n3. When prompted, place your NFC card on your device's NFC sensor:\n```\n[*] Place card on reader...\n```\n\n4. The framework will read the card and save its data:\n```\n[+] Card saved: 0A1B2C3D\n[+] File: ./cards/card_0A1B2C3D.json\n```\n\nThe card data is saved as a JSON file containing:\n- Card UID\n- Card type\n- NDEF data (if available)\n- MIFARE sector data (if it's a MIFARE card)\n- Raw dumps for advanced analysis\n\n### 2. Understanding the Card Data\n\nThe `read_card.py` script extracts several important elements from cards:\n\n```python\ntag_info = {\n    \"UID\": uid,                    # Unique identifier\n    \"Type\": str(tag),              # Card type (MIFARE, NTAG, etc.)\n    \"Technologies\": [...],         # Supported technologies\n    \"Timestamp\": int(time.time()), # When the card was read\n}\n```\n\nFor MIFARE cards, it also extracts sector data:\n```python\nif hasattr(tag, 'mifare'):\n    sectors_data = {}\n    for sector in range(16):\n        try:\n            blocks = tag.mifare.read_blocks(sector * 4, 4)\n            sectors_data[f\"sector_{sector}\"] = binascii.hexlify(blocks).decode()\n        except Exception as e:\n            sectors_data[f\"sector_{sector}\"] = f\"Error: {str(e)}\"\n    tag_info[\"MIFARE_Data\"] = sectors_data\n```\n\n### 3. Listing Saved Cards\n\n1. From the main menu, select option `2` (List Saved Cards).\n\n2. You'll see a table of all saved cards:\n```\n[*] Saved cards:\n----------------------------------------\n| UID                | Type            |\n----------------------------------------\n| 0A1B2C3D           | MIFARE Classic  |\n| E5F6G7H8           | NTAG215         |\n----------------------------------------\n```\n\nThe `list_saved_cards()` function in `card_utils.sh` handles this:\n```bash\nfunction list_saved_cards() {\n    load_config\n    \n    echo \"[*] Saved cards:\"\n    echo \"----------------------------------------\"\n    echo \"| UID                | Type            |\"\n    echo \"----------------------------------------\"\n    \n    find \"$CARD_DATA_DIR\" -name \"card_*.json\" | while read -r card_file; do\n        if [ -f \"$card_file\" ]; then\n            local uid=$(jq -r '.UID // \"Unknown\"' \"$card_file\")\n            local type=$(jq -r '.Type // \"Unknown\"' \"$card_file\")\n            local type_short=${type:0:15}\n            printf \"| %-18s | %-15s |\\n\" \"$uid\" \"$type_short\"\n        fi\n    done\n    echo \"----------------------------------------\"\n}\n```\n\n### 4. Analyzing a Card\n\n1. From the main menu, select option `5` (Analyze Card).\n\n2. Enter the UID of the card to analyze.\n\n3. View the detailed analysis:\n```\n[*] Card Analysis: 0A1B2C3D\n--------------------------------------------------\nType: MIFARE Classic 1K\n\nSupported Technologies:\n- mifare\n- ndef\n\nMIFARE Sectors:\nsector_0: 0A1B2C3D10480804...\nsector_1: 00000000000000...\n...\n```\n\nThe analysis is handled by the `analyze_card()` function in `utils.py`:\n```python\ndef analyze_card(uid):\n    \"\"\"Analyze a saved card and print detailed information\"\"\"\n    card_path = get_card_path(uid)\n    \n    if not os.path.exists(card_path):\n        print(f\"[!] Card not found: {uid}\")\n        return False\n    \n    try:\n        with open(card_path, 'r') as f:\n            card_data = json.load(f)\n        \n        print(f\"\\n[*] Card Analysis: {uid}\")\n        print(\"-\" * 50)\n        print(f\"Type: {card_data.get('Type', 'Unknown')}\")\n        \n        # More analysis code here...\n    \n    except Exception as e:\n        print(f\"[!] Error analyzing card: {str(e)}\")\n        return False\n```\n\n### 5. Emulating a Card\n\n1. From the main menu, select option `3` (Emulate NFC Card).\n\n2. Enter the UID of the card you want to emulate:\n```\n[?] Enter card UID to emulate: 0A1B2C3D\n```\n\n3. The emulation service will start:\n```\n[*] Preparing to emulate card: 0A1B2C3D\n[*] Card file: ./cards/card_0A1B2C3D.json\n[+] NFC emulation service started\n```\n\nThe emulation process:\n1. The `emulate_card.sh` script loads the card data\n2. It prepares a JSON settings file with the card details\n3. This is passed to the Android HCE component \n4. The Android app handles the actual emulation\n\nKey code from `emulate_card.sh`:\n```bash\n# Create a temporary JSON settings file for the Android app\nTEMP_SETTINGS=$(mktemp)\ncat \u003e \"$TEMP_SETTINGS\" \u003c\u003c EOF\n{\n    \"uid\": \"$CARD_UID\",\n    \"card_path\": \"$CARD_FILE\",\n    \"auto_response\": true\n}\nEOF\n\n# Copy settings to a location accessible by the app\nANDROID_STORAGE_PATH=\"/storage/emulated/0/Android/data/com.nfcclone.app/files\"\nmkdir -p \"$ANDROID_STORAGE_PATH\"\ncp \"$TEMP_SETTINGS\" \"$ANDROID_STORAGE_PATH/current_card.json\"\n\n# Start the NFC Emulator app\nam start -n com.nfcclone.app/.MainActivity --ez \"start_emulation\" true\n```\n\nThe core emulation occurs in `NfcEmulatorService.java`:\n```java\n@Override\npublic byte[] processCommandApdu(byte[] commandApdu, Bundle extras) {\n    Log.d(TAG, \"Received APDU: \" + bytesToHex(commandApdu));\n    \n    // If no card is loaded, return failure\n    if (emulatedUid == null) {\n        Log.e(TAG, \"No card data loaded for emulation\");\n        return FAILURE_SW;\n    }\n    \n    // Process SELECT command\n    if (Arrays.equals(SELECT_AID_COMMAND, commandApdu) || \n        (commandApdu.length \u003e= 5 \u0026\u0026 commandApdu[0] == (byte)0x00 \u0026\u0026 commandApdu[1] == (byte)0xA4)) {\n        Log.d(TAG, \"Received SELECT command, responding with success\");\n        return SUCCESS_SW;\n    }\n    \n    // Process GET UID command\n    if (commandApdu.length \u003e= 2 \u0026\u0026 commandApdu[0] == (byte)0xFF \u0026\u0026 commandApdu[1] == (byte)0xCA) {\n        Log.d(TAG, \"Received GET UID command, responding with UID\");\n        byte[] response = new byte[emulatedUid.length + 2];\n        System.arraycopy(emulatedUid, 0, response, 0, emulatedUid.length);\n        System.arraycopy(SUCCESS_SW, 0, response, emulatedUid.length, 2);\n        return response;\n    }\n    \n    // Use custom response if available\n    if (customResponse != null) {\n        return customResponse;\n    }\n    \n    // Default response\n    return SUCCESS_SW;\n}\n```\n\n4. Place your phone against the NFC reader to test the emulation.\n\n5. Press Ctrl+C to stop emulation when finished.\n\n### 6. Modifying Card Data\n\n1. From the main menu, select option `4` (Modify Card Data).\n\n2. Enter the UID of the card to modify.\n\n3. Choose a modification option:\n   - Edit custom response: Change how the card responds to commands\n   - Add label: Add a name to identify the card\n   - Edit raw data: Directly edit the JSON card file\n\nThe custom response option is particularly useful if the original reader expects specific responses:\n```bash\necho -n \"[?] Enter new custom response (hex, e.g. 9000): \"\nread -r new_response\njq \".custom_response = \\\"$new_response\\\"\" \"$card_file\" \u003e \"${card_file}.tmp\" \u0026\u0026 mv \"${card_file}.tmp\" \"$card_file\"\n```\n\n### 7. Exporting and Importing Cards\n\n1. From the main menu, select option `6` (Export/Import Card).\n\n2. To export a card (to share with others or backup):\n   - Select `1` (Export Card)\n   - Enter the card UID\n   - The card will be exported to a portable JSON format\n\n3. To import a card:\n   - Select `2` (Import Card)\n   - Enter the path to the import file\n   - The card will be added to your collection\n\n## Advanced Usage\n\n### Custom Card Responses for Specific Systems\n\nSome access systems check for specific responses. You can customize these:\n\n1. Log the responses from your original card using an NFC analyzer app\n2. Use the \"Edit custom response\" option to set the same response\n3. Test with the target system\n\n### Handling Encrypted Cards\n\nFor encrypted cards (like secure MIFARE DESFire):\n\n1. Reading will get the UID, which is often enough for basic emulation\n2. Some systems check only the UID, not the encrypted content\n3. If the system verifies cryptographic authentication, you'll need to use more advanced tools\n\n### Working with Different Card Types\n\nDifferent card types are handled in `read_card.py`:\n\n- MIFARE Classic: Tries to read all sectors\n- NDEF cards: Extracts NDEF records and text\n- Other cards: Gets basic identification info\n\nThe Android emulation component handles various card protocols in the HCE service.\n\n## Troubleshooting\n\n### Card Reading Problems\n\n- **Card not detected**: Check NFC is enabled in phone settings\n- **Read errors**: Some cards use encryption or proprietary protocols\n- **Incomplete data**: Some sectors may be protected, but the UID is always readable\n\n### Emulation Issues\n\n- **Emulation not working**: Verify Android HCE app installed correctly\n- **Reader rejects emulated card**: Modern systems may detect emulation\n- **Inconsistent results**: Try adjusting how you position the phone\n\n### NFC Compatibility\n\n- This framework works best with:\n  - MIFARE Classic 1K/4K\n  - NTAG21x series\n  - ISO 14443-A cards\n- Limited support for:\n  - MIFARE DESFire\n  - FeliCa\n  - ISO 14443-B\n\n## Advanced Setup: Rooting and Alternatives\n\n### Rooting Your Android Device\n\nRooting provides additional capabilities for NFC manipulation, including direct memory access to the NFC controller and bypassing Android security restrictions. With root access, you can:\n\n- Clone a wider range of NFC cards including some secured types\n- Directly manipulate the NFC hardware at a lower level\n- Use advanced emulation features not available through standard HCE\n\n\u003e ⚠️ **WARNING**: Rooting voids warranty, may trigger security measures, and could potentially brick your device if done incorrectly. Proceed at your own risk.\n\n#### General Rooting Methods\n\nEvery Android device has a different rooting procedure. Here's a general approach:\n\n1. **Preparation**:\n   ```bash\n   # Enable Developer Options:\n   Settings \u003e About Phone \u003e Tap \"Build Number\" 7 times\n   \n   # Enable USB Debugging and OEM Unlocking:\n   Settings \u003e Developer Options \u003e Enable both options\n   \n   # Install required tools on your computer:\n   # ADB and Fastboot tools from Android SDK Platform Tools\n   ```\n\n2. **Unlock Bootloader**:\n   ```bash\n   # Connect phone to computer via USB\n   adb devices                    # Verify connection\n   adb reboot bootloader          # Reboot to bootloader\n   \n   # Unlock bootloader (exact command varies by manufacturer)\n   fastboot flashing unlock       # For newer devices\n   # OR\n   fastboot oem unlock            # For older devices\n   ```\n\n3. **Install Custom Recovery**:\n   ```bash\n   # Download TWRP for your specific device from twrp.me\n   fastboot flash recovery twrp-[your-device]-[version].img\n   fastboot reboot recovery\n   ```\n\n4. **Install Magisk**:\n   - Download latest Magisk APK from [GitHub](https://github.com/topjohnwu/Magisk/releases)\n   - Rename it to Magisk.zip\n   - Transfer to your device\n   - In TWRP, select \"Install\" and choose the Magisk.zip file\n   - Reboot system\n\n#### Device-Specific Guides\n\nFor model-specific instructions, search:\n- XDA Developers forums for your device model\n- Manufacturer-specific methods:\n  - Samsung: Use Odin with patched AP files\n  - Pixel: Special fastboot commands\n  - Xiaomi: Request unlock permission through Mi Unlock tool\n  - OnePlus: Relatively straightforward bootloader unlock\n\n#### Verifying Root for NFCman:\n\n```bash\n# In Termux:\npkg install root-repo\npkg install tsu\ntsu                       # Should give you a # prompt if root works\nwhoami                    # Should display \"root\"\n\n# Check NFC hardware access\nls -la /dev/nfc*          # Should show NFC device files\n```\n\n### Alternative: Using Termux with X11 Environment\n\nIf you can't or don't want to root your device, you can set up a graphical environment in Termux to use additional NFC tools through a GUI interface:\n\n1. **Install Required Packages**:\n   ```bash\n   pkg update \u0026\u0026 pkg upgrade\n   pkg install x11-repo\n   pkg install xorg-server tigervnc xfce4 aterm\n   ```\n\n2. **Configure VNC Server**:\n   ```bash\n   vncserver -localhost    # Start VNC server\n   # Set a password when prompted\n   \n   # Create startup file\n   mkdir -p ~/.vnc\n   cat \u003e ~/.vnc/xstartup \u003c\u003c 'EOF'\n   #!/data/data/com.termux/files/usr/bin/bash\n   xrdb $HOME/.Xresources\n   xfce4-session \u0026\n   EOF\n   \n   chmod +x ~/.vnc/xstartup\n   ```\n\n3. **Kill existing server and restart properly**:\n   ```bash\n   vncserver -kill :1\n   vncserver -geometry 1280x720 -localhost :1\n   ```\n\n4. **Install VNC Viewer**:\n   - Install a VNC client app from Google Play (like VNC Viewer by RealVNC)\n   - Configure connection to: localhost:5901\n   - Enter the password you set earlier\n\n5. **Install and Run NFC Tools in X11**:\n   ```bash\n   # In your VNC X11 session terminal\n   pkg install python-tkinter\n   \n   # Install graphical NFC tools\n   pip install nfcpy-gui\n   \n   # Create a launcher script for the NFC GUI tool\n   cat \u003e ~/nfc-gui.sh \u003c\u003c 'EOF'\n   #!/data/data/com.termux/files/usr/bin/bash\n   cd $HOME\n   python -c \"import nfcpy_gui; nfcpy_gui.main()\"\n   EOF\n   \n   chmod +x ~/nfc-gui.sh\n   ```\n\n6. **Run the GUI Tool**:\n   - From the X11 desktop, open a terminal\n   - Execute `~/nfc-gui.sh`\n   - The graphical NFC tool will allow you to scan and analyze cards\n\nThis X11 setup provides a desktop-like environment for working with NFC tools that have graphical interfaces, offering an alternative approach for users who prefer visual tools or cannot root their devices.\n\n## Security Considerations\n\n- Only clone cards you own or have permission to clone\n- Be aware that bypassing access control may violate terms of service or laws\n- This tool is for educational and personal use\n- Cards containing financial data (credit cards, etc.) use strong encryption and cannot be cloned with this tool\n\n## Legal Disclaimer\n\nThis framework is provided for educational purposes only. Use at your own risk and responsibility. The developers are not responsible for any misuse.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpscript%2Fnfcman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcpscript%2Fnfcman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpscript%2Fnfcman/lists"}