147 lines
3.3 KiB
Markdown
147 lines
3.3 KiB
Markdown
# MAC Address Vendor Lookup API
|
|
A FastAPI service that identifies network device manufacturers from MAC addresses using a three-tier lookup strategy for optimal performance and reliability.
|
|
|
|
## Features
|
|
- **Multi-format MAC address support**: Accepts various formats (with/without separators)
|
|
- **Partial MAC lookup**: Works with full addresses or just the first 6 digits (OUI)
|
|
- **Three-tier lookup strategy**:
|
|
1. Local file cache (fastest)
|
|
2. GitHub vendor database fallback
|
|
3. External API fallback (macvendors.com)
|
|
- **Standardized output**: Returns MAC addresses in dash-separated format
|
|
|
|
## Supported MAC Address Formats
|
|
All of these formats are accepted:
|
|
- `000000` (OUI only)
|
|
- `00:00:01`
|
|
- `00-00-02-AB-CD-EF`
|
|
- `000003ABCDEF`
|
|
- `00 00 04 12 34 56`
|
|
- `70-2A:54` (mixed formats)
|
|
- `702A-54` (partial mixed)
|
|
|
|
## How to Deploy
|
|
|
|
### Using Docker Compose
|
|
```yml
|
|
services:
|
|
api:
|
|
image: git.shihaam.dev/shihaam/macvendors
|
|
ports:
|
|
- 5000:8000
|
|
```
|
|
|
|
### Using Docker
|
|
```bash
|
|
# Pull and run
|
|
docker run -p 5000:8000 git.shihaam.dev/shihaam/macvendors
|
|
|
|
# With local MAC vendor file
|
|
docker run -p 5000:8000 -v $(pwd)/mac_list.txt:/app/mac_list.txt git.shihaam.dev/shihaam/macvendors
|
|
```
|
|
|
|
### Local Development
|
|
```bash
|
|
# Install dependencies
|
|
pip install fastapi uvicorn httpx
|
|
|
|
# Run the server
|
|
uvicorn macvendorapi:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
## API Usage
|
|
|
|
### Endpoint
|
|
```
|
|
GET /lookup/{mac_address}
|
|
```
|
|
|
|
### Examples
|
|
```bash
|
|
# Basic lookup
|
|
curl http://localhost:5000/lookup/70-22-FE
|
|
|
|
# Different formats
|
|
curl http://localhost:5000/lookup/7022FE
|
|
curl http://localhost:5000/lookup/70:22:FE
|
|
curl http://localhost:5000/lookup/70-22-FE-12-34-56
|
|
```
|
|
|
|
## Response Format
|
|
|
|
### Success Response (HTTP 200)
|
|
When a vendor is found:
|
|
```json
|
|
{
|
|
"mac_address": "70-22-FE",
|
|
"vendor": "Apple, Inc.",
|
|
"detail": null
|
|
}
|
|
```
|
|
|
|
### Not Found Response (HTTP 404)
|
|
When MAC address is valid but vendor is not found:
|
|
```json
|
|
{
|
|
"mac_address": "70-22-54",
|
|
"vendor": null,
|
|
"detail": "Vendor not found"
|
|
}
|
|
```
|
|
|
|
### Error Response (HTTP 400)
|
|
When MAC address format is invalid:
|
|
```json
|
|
{
|
|
"mac_address": "70-22-HI",
|
|
"vendor": null,
|
|
"detail": "Invalid MAC address format"
|
|
}
|
|
```
|
|
|
|
## HTTP Status Codes
|
|
- **200 OK**: Valid MAC address with vendor found
|
|
- **400 Bad Request**: Invalid MAC address format
|
|
- **404 Not Found**: Valid MAC address but vendor not found
|
|
|
|
## Local MAC Vendor File
|
|
To improve performance, you can provide a local `mac_list.txt` file in the same format as the [IEEE OUI database](https://gist.githubusercontent.com/aallan/b4bb86db86079509e6159810ae9bd3e4/raw/846ae1b646ab0f4d646af9115e47365f4118e5f6/mac-vendor.txt):
|
|
|
|
```
|
|
000000 Officially Xerox
|
|
000001 SuperLAN-2U
|
|
000002 BBN (was internal usage only, no longer used)
|
|
000003 XEROX CORPORATION
|
|
```
|
|
|
|
## Lookup Strategy
|
|
1. **Local File**: Checks `mac_list.txt` first (fastest, no network calls)
|
|
2. **GitHub Database**: Falls back to the official IEEE OUI database
|
|
3. **External API**: Uses macvendors.com API as final fallback
|
|
4. **Not Found**: Returns vendor not found if no matches are found
|
|
|
|
## Building from Source
|
|
```bash
|
|
# Clone repository
|
|
git clone <repository-url>
|
|
cd macvendors
|
|
|
|
# Build Docker image
|
|
docker build -t mac-vendor-api .
|
|
|
|
# Run container
|
|
docker run -p 8000:8000 mac-vendor-api
|
|
```
|
|
|
|
## Health Check
|
|
```bash
|
|
curl http://localhost:5000/
|
|
```
|
|
|
|
Returns:
|
|
```json
|
|
{
|
|
"message": "MAC Address Vendor Lookup API"
|
|
}
|
|
```
|