diff --git a/.github/SOCIAL_PREVIEW_SETUP.md b/.github/SOCIAL_PREVIEW_SETUP.md new file mode 100644 index 0000000..c86d975 --- /dev/null +++ b/.github/SOCIAL_PREVIEW_SETUP.md @@ -0,0 +1,128 @@ +# Social Preview Image Setup + +This guide explains how to set up the social preview image for the PrivaseeAI.Security repository on GitHub. + +## About the Image + +The social preview image (`social-preview.png`) is an architectural diagram that displays when the repository is shared on social media platforms like Twitter, LinkedIn, or Facebook. + +**Image Details:** +- **Dimensions:** 1280×640 pixels (GitHub recommended size) +- **Format:** PNG +- **Size:** ~49KB +- **Location:** `.github/assets/social-preview.png` + +**Features Highlighted:** +- PrivaseeAI.Security branding +- Real-Time iOS Threat Detection & Monitoring subtitle +- Architectural diagram showing system components: + - CLI Interface + - Threat Orchestrator + - VPN Integrity Monitor + - API Abuse Monitor + - Carrier Compromise Detector + - Backup Monitor + - Telegram Alerter +- Key statistics: Battle-Tested, Privacy-First, Real-Time, 196 Tests + +## How to Set the Social Preview on GitHub + +**Note:** Setting the social preview image requires repository administrator access and must be done through the GitHub web interface. + +### Step-by-Step Instructions: + +1. **Navigate to Repository Settings** + - Go to https://github.com/aurelianware/PrivaseeAI.Security + - Click on the **Settings** tab (requires admin access) + +2. **Find the Social Preview Section** + - Scroll down to the **Social preview** section + - It's located near the top of the Settings page + +3. **Upload the Image** + - Click **Edit** next to the social preview section + - Click **Upload an image...** + - Select the file: `.github/assets/social-preview.png` from your local clone + - Alternatively, download it from the repository first, then upload it + +4. **Verify and Save** + - Preview the image in the dialog + - Click **Save** or **Set as preview** to confirm + - The image should now appear in the Social preview section + +### Verification + +After uploading, you can verify the social preview is working: + +1. **Check the Settings page** - The preview should display in the Social preview section +2. **Share on social media** - Share the repository URL on Twitter, LinkedIn, or Facebook to see the preview in action +3. **Use Twitter Card Validator** - Visit https://cards-dev.twitter.com/validator and enter your repo URL +4. **Use LinkedIn Post Inspector** - Visit https://www.linkedin.com/post-inspector/ and enter your repo URL + +## Image Requirements (Reference) + +GitHub's requirements for social preview images: + +- **Minimum dimensions:** 640×320 pixels +- **Recommended dimensions:** 1280×640 pixels (what we use) +- **Maximum file size:** 1 MB +- **Supported formats:** PNG, JPG, GIF +- **Aspect ratio:** 2:1 (width:height) + +Our image meets all these requirements. + +## Updating the Image + +If you need to update the social preview image in the future: + +1. **Regenerate the image** using the Python script (see below) +2. **Replace** `.github/assets/social-preview.png` in the repository +3. **Re-upload** to GitHub following the steps above + +### Regenerating the Image + +The image was created using Python and Pillow. To recreate or modify it: + +```bash +# Install Pillow if needed +pip install Pillow + +# Run the generation script +python scripts/generate_social_preview.py + +# Or create your own script based on the original +``` + +The original script used: +- **Background:** GitHub dark theme (#0D1117) +- **Primary color:** GitHub blue (#58A6FF) +- **Secondary color:** GitHub green (#7EE787) +- **Accent color:** GitHub red (#F85149) +- **Purple color:** GitHub purple (#BC8CFF) +- **Font:** DejaVu Sans (Bold for title, Regular for text) + +## Troubleshooting + +**Issue:** Can't find the Settings tab +- **Solution:** You need repository administrator access. Contact the repository owner. + +**Issue:** Image doesn't appear after uploading +- **Solution:** Clear your browser cache and reload. It may take a few minutes to propagate. + +**Issue:** Image looks blurry or pixelated +- **Solution:** Ensure you're uploading the full-resolution 1280×640 image, not a scaled-down version. + +**Issue:** Image is rejected during upload +- **Solution:** Verify the file is under 1 MB and in PNG, JPG, or GIF format. + +## Resources + +- [GitHub Docs: Customizing your repository's social media preview](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview) +- [Open Graph Protocol](https://ogp.me/) +- [Twitter Card Validator](https://cards-dev.twitter.com/validator) + +## Questions? + +If you have questions about the social preview image setup, please: +- Open an issue in the repository +- Contact: support@aurelianware.com diff --git a/.github/assets/social-preview.png b/.github/assets/social-preview.png new file mode 100644 index 0000000..9725500 Binary files /dev/null and b/.github/assets/social-preview.png differ diff --git a/README.md b/README.md index b693c0e..e4d2230 100644 --- a/README.md +++ b/README.md @@ -234,6 +234,7 @@ echo "TELEGRAM_CHAT_ID=your_chat_id" >> .env - **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute - **[SECURITY.md](SECURITY.md)** - Security policy and vulnerability reporting - **[TESTING_SUMMARY.md](TESTING_SUMMARY.md)** - Test infrastructure overview +- **[.github/SOCIAL_PREVIEW_SETUP.md](.github/SOCIAL_PREVIEW_SETUP.md)** - Social media preview image setup ## 🎯 Use Cases diff --git a/requirements-dev.txt b/requirements-dev.txt index 7b8e2bc..a4da927 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -17,3 +17,6 @@ mypy>=1.0.0 # Development utilities ipython>=8.12.0 ipdb>=0.13.13 + +# Image generation (for social preview) +Pillow>=10.0.0 diff --git a/scripts/generate_social_preview.py b/scripts/generate_social_preview.py new file mode 100755 index 0000000..dae97b3 --- /dev/null +++ b/scripts/generate_social_preview.py @@ -0,0 +1,295 @@ +#!/usr/bin/env python3 +""" +Generate social preview image for PrivaseeAI.Security repository + +This script creates a 1280x640 PNG image with an architectural diagram +showing the main components of the PrivaseeAI.Security system. + +This is a development/maintenance utility and requires the Pillow +library (PIL), which is not installed by default. + +Install with: + pip install Pillow + +Usage: + python scripts/generate_social_preview.py [--output OUTPUT_PATH] + +The generated image can be uploaded to GitHub as the repository's +social preview image (Settings > Social preview). +""" + +import argparse +from pathlib import Path +import sys + +try: + from PIL import Image, ImageDraw, ImageFont +except ImportError as exc: + sys.stderr.write( + "Error: The Pillow library (PIL) is required to run this script.\n" + "Install it with:\n" + " pip install Pillow\n" + ) + raise SystemExit(1) from exc + + +# Image dimensions (GitHub recommended: 1280x640) +WIDTH = 1280 +HEIGHT = 640 + +# Color scheme - Security/Privacy theme (GitHub dark colors) +BG_COLOR = "#0D1117" # GitHub dark background +PRIMARY_COLOR = "#58A6FF" # GitHub blue +SECONDARY_COLOR = "#7EE787" # GitHub green +TEXT_COLOR = "#C9D1D9" # GitHub text +ACCENT_COLOR = "#F85149" # GitHub red (for alerts/threats) +PURPLE_COLOR = "#BC8CFF" # GitHub purple + +# Layout constants - extracted for maintainability +# Margins and positions +MARGIN_LEFT = 50 +TITLE_Y = 40 +SUBTITLE_Y = 130 + +# CLI Interface box +CLI_Y = 200 +CLI_RIGHT = 1230 +CLI_HEIGHT = 60 +CLI_TEXT_X = 520 +CLI_TEXT_Y_OFFSET = 20 + +# Orchestrator box +ORCH_Y_SPACING = 80 +ORCH_LEFT = 400 +ORCH_RIGHT = 880 +ORCH_HEIGHT = 50 +ORCH_TEXT_X = 520 +ORCH_TEXT_Y_OFFSET = 15 +ORCH_CENTER_X = 640 +ORCH_ARROW_Y = 330 + +# Monitor boxes +MONITOR_Y_SPACING = 70 +MONITOR_BOX_WIDTH = 250 +MONITOR_BOX_HEIGHT = 60 +MONITOR_SPACING = 50 +MONITOR_X_START = 80 +MONITOR_TEXT_X_OFFSET = 60 +MONITOR_TEXT_Y_OFFSET = 10 +MONITOR_TEXT_LINE_HEIGHT = 25 +MONITOR_ARROW_Y = 350 + +# Alerter box +ALERTER_Y_SPACING = 90 +ALERTER_LEFT = 400 +ALERTER_RIGHT = 880 +ALERTER_HEIGHT = 50 +ALERTER_TEXT_X = 520 +ALERTER_TEXT_Y_OFFSET = 15 +ALERTER_ARROW_Y = 510 +ALERTER_ARROW_Y_OFFSET = 30 + +# Footer +FOOTER_Y = 580 +FOOTER_X = 180 + +# Arrow constants +CLI_ORCH_ARROW_START_Y = 260 +CLI_ORCH_ARROW_END_Y = 280 +ARROW_WIDTH = 2 + +# Box border width +BOX_BORDER_WIDTH = 3 + +# Font sizes +TITLE_FONT_SIZE = 72 +SUBTITLE_FONT_SIZE = 32 +TEXT_FONT_SIZE = 24 +SMALL_FONT_SIZE = 20 + +# Common font paths across different operating systems +FONT_PATHS = [ + # Linux + "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", + "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", + # macOS + "/System/Library/Fonts/Supplemental/Arial Bold.ttf", + "/System/Library/Fonts/Supplemental/Arial.ttf", + "/Library/Fonts/Arial Bold.ttf", + "/Library/Fonts/Arial.ttf", + # Windows (via Wine or WSL) + "C:\\Windows\\Fonts\\arialbd.ttf", + "C:\\Windows\\Fonts\\arial.ttf", +] + + +def hex_to_rgb(hex_color): + """Convert hex color to RGB tuple""" + hex_color = hex_color.lstrip('#') + return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4)) + + +def find_font(font_paths, size): + """ + Try to find a working font from a list of paths. + + Args: + font_paths: List of font file paths to try + size: Font size + + Returns: + ImageFont object (truetype if found, default otherwise) + """ + for font_path in font_paths: + try: + return ImageFont.truetype(font_path, size) + except (IOError, OSError): + continue + + # No fonts found, return default + sys.stderr.write("Warning: Could not find fonts at standard locations, using default font\n") + return ImageFont.load_default() + + +def create_social_preview(output_path): + """ + Create the social preview image + + Args: + output_path: Path where the image will be saved + """ + + # Create image with dark background + img = Image.new('RGB', (WIDTH, HEIGHT), hex_to_rgb(BG_COLOR)) + draw = ImageDraw.Draw(img) + + # Load fonts with cross-platform support + # Try bold fonts first for title + bold_font_paths = [p for p in FONT_PATHS if 'Bold' in p or 'bold' in p] + regular_font_paths = [p for p in FONT_PATHS if 'Bold' not in p and 'bold' not in p] + + title_font = find_font(bold_font_paths, TITLE_FONT_SIZE) + subtitle_font = find_font(regular_font_paths, SUBTITLE_FONT_SIZE) + text_font = find_font(regular_font_paths, TEXT_FONT_SIZE) + small_font = find_font(regular_font_paths, SMALL_FONT_SIZE) + + # Title + title = "PrivaseeAI.Security" + draw.text((MARGIN_LEFT, TITLE_Y), title, fill=hex_to_rgb(PRIMARY_COLOR), font=title_font) + + # Subtitle + subtitle = "Real-Time iOS Threat Detection & Monitoring" + draw.text((MARGIN_LEFT, SUBTITLE_Y), subtitle, fill=hex_to_rgb(TEXT_COLOR), font=subtitle_font) + + # Architecture diagram + y_offset = CLI_Y + + # Top: CLI Interface + draw.rectangle([MARGIN_LEFT, y_offset, CLI_RIGHT, y_offset + CLI_HEIGHT], + outline=hex_to_rgb(PRIMARY_COLOR), width=BOX_BORDER_WIDTH) + draw.text((CLI_TEXT_X, y_offset + CLI_TEXT_Y_OFFSET), "CLI Interface", + fill=hex_to_rgb(PRIMARY_COLOR), font=text_font) + + # Middle: Orchestrator + y_offset += ORCH_Y_SPACING + draw.rectangle([ORCH_LEFT, y_offset, ORCH_RIGHT, y_offset + ORCH_HEIGHT], + outline=hex_to_rgb(SECONDARY_COLOR), width=BOX_BORDER_WIDTH) + draw.text((ORCH_TEXT_X, y_offset + ORCH_TEXT_Y_OFFSET), "Threat Orchestrator", + fill=hex_to_rgb(SECONDARY_COLOR), font=text_font) + + # Bottom: Monitors (4 boxes) + y_offset += MONITOR_Y_SPACING + + monitors = [ + ("VPN\nIntegrity", PRIMARY_COLOR), + ("API\nAbuse", PURPLE_COLOR), + ("Carrier\nCompromise", ACCENT_COLOR), + ("Backup\nMonitor", SECONDARY_COLOR) + ] + + for i, (monitor, color) in enumerate(monitors): + x = MONITOR_X_START + i * (MONITOR_BOX_WIDTH + MONITOR_SPACING) + draw.rectangle([x, y_offset, x + MONITOR_BOX_WIDTH, y_offset + MONITOR_BOX_HEIGHT], + outline=hex_to_rgb(color), width=BOX_BORDER_WIDTH) + lines = monitor.split('\n') + for j, line in enumerate(lines): + draw.text((x + MONITOR_TEXT_X_OFFSET, y_offset + MONITOR_TEXT_Y_OFFSET + j * MONITOR_TEXT_LINE_HEIGHT), + line, fill=hex_to_rgb(color), font=small_font) + + # Alert system at bottom + y_offset += ALERTER_Y_SPACING + draw.rectangle([ALERTER_LEFT, y_offset, ALERTER_RIGHT, y_offset + ALERTER_HEIGHT], + outline=hex_to_rgb(ACCENT_COLOR), width=BOX_BORDER_WIDTH) + draw.text((ALERTER_TEXT_X, y_offset + ALERTER_TEXT_Y_OFFSET), "Telegram Alerter", + fill=hex_to_rgb(ACCENT_COLOR), font=text_font) + + # Add arrows/connections (simplified) + # Arrow from CLI to Orchestrator + draw.line([(ORCH_CENTER_X, CLI_ORCH_ARROW_START_Y), (ORCH_CENTER_X, CLI_ORCH_ARROW_END_Y)], + fill=hex_to_rgb(TEXT_COLOR), width=ARROW_WIDTH) + + # Arrows from Orchestrator to monitors + for i in range(4): + monitor_x = MONITOR_X_START + MONITOR_BOX_WIDTH // 2 + i * (MONITOR_BOX_WIDTH + MONITOR_SPACING) + draw.line([(ORCH_CENTER_X, ORCH_ARROW_Y), (monitor_x, MONITOR_ARROW_Y)], + fill=hex_to_rgb(TEXT_COLOR), width=ARROW_WIDTH) + + # Arrows from monitors to alerter + for i in range(4): + monitor_x = MONITOR_X_START + MONITOR_BOX_WIDTH // 2 + i * (MONITOR_BOX_WIDTH + MONITOR_SPACING) + draw.line([(monitor_x, y_offset - ALERTER_ARROW_Y_OFFSET), (ORCH_CENTER_X, ALERTER_ARROW_Y)], + fill=hex_to_rgb(TEXT_COLOR), width=ARROW_WIDTH) + + # Footer with key features + features = "🛡️ Battle-Tested • 🔒 Privacy-First • ⚡ Real-Time • ✅ 196 Tests" + draw.text((FOOTER_X, FOOTER_Y), features, fill=hex_to_rgb(TEXT_COLOR), font=small_font) + + # Save the image with error handling + try: + img.save(output_path) + except OSError as e: + sys.stderr.write(f"Error: Failed to save image to '{output_path}': {e}\n") + sys.exit(1) + + # Try to determine file size; if it fails, continue without it + try: + file_size_kb = Path(output_path).stat().st_size / 1024 + except OSError as e: + sys.stderr.write(f"Warning: Image saved but failed to retrieve file size for '{output_path}': {e}\n") + file_size_kb = None + + print(f"Social preview image created: {output_path}") + print(f"Dimensions: {WIDTH}x{HEIGHT}") + if file_size_kb is not None: + print(f"File size: {file_size_kb:.1f} KB") + + +def main(): + """Main entry point""" + parser = argparse.ArgumentParser( + description='Generate social preview image for PrivaseeAI.Security repository' + ) + parser.add_argument( + '--output', + default='.github/assets/social-preview.png', + help='Output path for the generated image (default: .github/assets/social-preview.png)' + ) + + args = parser.parse_args() + + # Ensure output directory exists + output_path = Path(args.output) + output_path.parent.mkdir(parents=True, exist_ok=True) + + # Generate the image + create_social_preview(str(output_path)) + + print("\nNext steps:") + print("1. Review the generated image") + print("2. Go to GitHub repository Settings > Social preview") + print("3. Upload the image") + print("4. See .github/SOCIAL_PREVIEW_SETUP.md for detailed instructions") + + +if __name__ == '__main__': + main()