codefilterph-logcollector 0.1.1__py3-none-any.whl

codefilterph_logcollector-0.1.1.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: codefilterph-logcollector
+Version: 0.1.1
+Summary: Django Nginx log collection, security monitoring, and remote collector dashboards
+Author: CodefilterPH | Euge
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/codefilterPH/logcollector/tree/main/log_collector/docs
+Project-URL: Source, https://github.com/codefilterPH/logcollector
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Logging
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django<6.1,>=6.0
+Requires-Dist: channels<5,>=4.2
+Requires-Dist: celery<6,>=5.5
+Requires-Dist: djangorestframework<4,>=3.16
+Requires-Dist: requests<3,>=2.32
+Requires-Dist: cryptography<47,>=44
+Provides-Extra: redis
+Requires-Dist: channels-redis<5,>=4.2; extra == "redis"
+Provides-Extra: asgi
+Requires-Dist: daphne<5,>=4.2; extra == "asgi"
+Dynamic: license-file
+
+# LOG Collector
+
+Developed by: CodefilterPH | Euge
+
+LOG Collector is a Django application for local Nginx access-log collection,
+security incidents, API access, WebSocket updates, Celery processing, and
+read-only connections to other LOG Collector installations. CrowdSec connection
+management is included in the distribution.
+
+Install with `pip install codefilterph-logcollector`. Add `log_collector` and
+`crowdsec_integration` to `INSTALLED_APPS`, mount `log_collector.urls`, and run
+migrations. Nginx file access, ASGI, a channel layer, and Celery services are
+configured by the host project; installing the wheel does not provision them.
+
+The developer guides are installed in `log_collector/docs/` inside the Python
+package and are also available in the source repository:
+
+- [Installation](https://github.com/codefilterPH/logcollector/blob/main/log_collector/docs/installation.md)
+- [Configuration](https://github.com/codefilterPH/logcollector/blob/main/log_collector/docs/configuration.md)
+- [API integration](https://github.com/codefilterPH/logcollector/blob/main/log_collector/docs/api.md)
+- [Operations](https://github.com/codefilterPH/logcollector/blob/main/log_collector/docs/operations-guide.md)
+
+The app title defaults to **LOG Collector**. A Django superuser can set the
+displayed title and shared theme on the hosting entity Manage page. The developer
+credit is fixed in the application and cannot be edited through its settings.
+
+License: [MIT](LICENSE).
+
+Release owner: [first-release account setup](https://github.com/codefilterPH/logcollector/blob/main/RELEASE_SETUP.md).

codefilterph_logcollector-0.1.1.dist-info/RECORD

@@ -0,0 +1,55 @@
+codefilterph_logcollector-0.1.1.dist-info/licenses/LICENSE,sha256=chffrjMT2T1CXDMOfiCwn8vsuqK7RiE2seq-T9y2de8,1076
+crowdsec_integration/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+crowdsec_integration/apps.py,sha256=wWdHYhnPUIWY0Hi-bhlau0dcbVKanspW3yFDWc8vEXA,171
+crowdsec_integration/models.py,sha256=szYmtSg3PrLIiG9n_MefUP0ZaM-Uu-2-cdOGue8kbNc,465
+crowdsec_integration/services.py,sha256=_Ut0nYvielvj3il9cj47S2CI7zc8DHKZXpsWCg0kRvQ,2463
+crowdsec_integration/migrations/0001_initial.py,sha256=zbm074Cr9eCGt1GQwfdCN-_eWW2yJi7D9cPmJUeiA_g,856
+crowdsec_integration/migrations/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+log_collector/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+log_collector/apps.py,sha256=AdWJAgeU6DKycMnWSKejH52l_XpbL7t4d57Pfwen9KI,342
+log_collector/consumers.py,sha256=A4AO91tAsNOBmf3tCwzH9BZiLRD1fj7GFkL5KJw5F0w,2410
+log_collector/forms.py,sha256=uDrys5qc5ucM66MLLDK_vEPzeW1jUOYRm-kw0szB5NU,5737
+log_collector/integrations.py,sha256=HcbYzb42uqKmTZ6fiimbU9JEJ-AeNzYvou4B2_N3oPI,1765
+log_collector/middleware.py,sha256=_R52ieXiNCRjBzPVd0ZhwtNJ1p1H5CpENYmeasG_EGk,1998
+log_collector/models.py,sha256=w_9Xon3jx9t68UeOCdi0mc0cZ5j3f2xDrV0tMWvN_4g,21577
+log_collector/permissions.py,sha256=H3Tyt-bcSYgjFfjiYl3AjACVteVy2R4NaZ5If21_OSQ,9518
+log_collector/routing.py,sha256=o95rg-lnEvS4dgGN5svxV-2JiCwJ5ka1yYg6RMIjahY,4199
+log_collector/security_events.py,sha256=TbOsS58Gzpkk1cvgCfNik-EwjWZ9MKw5wK3OD0Z5was,1610
+log_collector/tasks.py,sha256=wVbsbbkSjszdJbaWVF9IGiqLFlkLrdT7K4eYtrDJby4,10494
+log_collector/urls.py,sha256=GVporqY0Eg3PGJ7whjiUMXvRwUlLyStGaSySyslGqWY,3114
+log_collector/views.py,sha256=iQF_zSv_I0vIax7mb3zEFZpJ9aRGntCHTaeY1AYjpcw,81382
+log_collector/docs/api.md,sha256=ylUXNCPFVzVkAfbXCH3FsAVdbjTPZ6pOiQ8J_0LPycg,1593
+log_collector/docs/configuration.md,sha256=5KsaSW2EtuYcATgVx_Iens_xBIABWtyjSOI5ZdOSsd8,3761
+log_collector/docs/installation.md,sha256=MdOg_mVxcRmAXizn-Ab1TuKyJclPOHUMPHaHmBxoEJQ,1460
+log_collector/docs/operations-guide.md,sha256=i1Ib_c07T1uOjvf7vpPnDiqGN54qTja2kjl-vogsytg,3118
+log_collector/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+log_collector/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+log_collector/management/commands/backfill_security_incidents.py,sha256=N_45cF5QMjkTrst7fNYD3nmYVRULg8bi6rQR6CQah_I,1492
+log_collector/management/commands/manage_security_block.py,sha256=ReW78tWLjMsJl2dvPC7tjadHtCNerp-T1xLegjpK7Qg,2833
+log_collector/management/commands/retry_security_sms.py,sha256=Gyd3rDGGGKxfSs1T-VyWQWDUbwkhjRdbQ67ohMFeUTg,1363
+log_collector/migrations/0001_initial.py,sha256=kY_ocOXBxvm149C3LI8MaRHk7HUUEABtYgKFzG40Lps,7415
+log_collector/migrations/0002_remove_logcollectorentity_allowed_api_key_names_and_more.py,sha256=XR4EX-mbg5P3hiTHP8j3BONCD_2U37JF-Qd-dx8tlLI,4054
+log_collector/migrations/0003_blockedipaddress_securityincident_ipblockauditevent_and_more.py,sha256=gOuFGdShB2ZwA8rt-xAG7U5oeMND080OnrFEm9qTqTE,11466
+log_collector/migrations/0004_app_appearance.py,sha256=zq1MZjPGhvkOi3Kkxy9I5aT5yPChfLs4Q9V4d5wxJkM,947
+log_collector/migrations/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+log_collector/services/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+log_collector/services/blocking.py,sha256=jL9OvyK-Xs6gdV-3xlS1WuUitkFjWbaA2L4REwk-Jyg,15867
+log_collector/services/client_ip.py,sha256=SGd-XtjiapVBlkDBJJEuUvvDDICwcIuSX3KPIwmURJ4,2463
+log_collector/services/incidents.py,sha256=MJPDREA9FGVfE0h3Gk27hz862pET__ZpKWY_5FVIbLQ,16539
+log_collector/services/nginx.py,sha256=3vt2bIIfA6Xf_p7iV3okqoAd2KowFxUc4PWGlTgHiK4,1727
+log_collector/services/remote.py,sha256=f55fgBSESu6wbg_cXuB0fghQzg2KkVcznIgNIvYZWzQ,1030
+log_collector/services/response.py,sha256=HwQ-FSaGf1d67KIMGlhdlmbNQ-fctRfl9jMHgYL5skw,3449
+log_collector/services/security.py,sha256=eegvTfLRJp2pL2ZDQ412y_5W7SlIVbgUPLRWU-JnXqw,15962
+log_collector/services/security_sms.py,sha256=q2rdnP8maLrnjcxNEbZzKfIqtSy6AfBYaXUbQmJCK5c,3545
+log_collector/services/sync.py,sha256=-o3fh5w9QIrjpnGgmfolKLT-Q_U8i5QqZrK1NDbCwUc,4187
+log_collector/services/trusted_ips.py,sha256=Y0HKq4O7M3_bq6r6yGNuXNOqzP0evBkrlZMJXrXmARw,1717
+log_collector/static/log_collector/appearance.css,sha256=ZqoaaK0yg2zKuWBGM7SKBCRHUsqIlWcQ5kbkIjNZbZU,1948
+log_collector/templates/log_collector/dashboard.html,sha256=5kARivEs_S5nXPgiOd-eMjxeyWfCrpxUxFbSO23fWI4,76757
+log_collector/templates/log_collector/entity_form.html,sha256=L7dzHqUgty8fkoQevLVhf08xah0ucdsHT3wcuNlK4TU,2648
+log_collector/templates/log_collector/entity_manage.html,sha256=ZJTHtc5SJhNAtXEhCzmqblkH2k_3KA1tSI66D_Tf9AA,21626
+log_collector/templates/log_collector/entity_selection.html,sha256=o4w3V-GFtpimIVwmDxsIP4MNxsXahDtyQccc1Q8F3C0,8433
+log_collector/templates/log_collector/security_report.html,sha256=cGMMMRGpynd4LEMorQodpCLZXg_Br-BIBTJcSX1xHBQ,7114
+codefilterph_logcollector-0.1.1.dist-info/METADATA,sha256=kNe3JdRHv4bAdAlF_KmjNvSXwjSbMolaJYQqKtWSEc8,2613
+codefilterph_logcollector-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+codefilterph_logcollector-0.1.1.dist-info/top_level.txt,sha256=9w5wgE9-NeX0_DLqK78SHfg4OJrBFCjn6li-h0TiyvQ,35
+codefilterph_logcollector-0.1.1.dist-info/RECORD,,

codefilterph_logcollector-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codefilterph_logcollector-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodefilterPH | Euge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codefilterph_logcollector-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+crowdsec_integration
+log_collector

crowdsec_integration/__init__.py

@@ -0,0 +1 @@
+

crowdsec_integration/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class CrowdSecIntegrationConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "crowdsec_integration"

crowdsec_integration/migrations/0001_initial.py

@@ -0,0 +1,22 @@
+"""Initial CrowdSec connection schema for standalone installations."""
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+    dependencies = []
+    operations = [
+        migrations.CreateModel(
+            name="CrowdSecConnection",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("entity_id", models.PositiveBigIntegerField(db_index=True, unique=True)),
+                ("api_url", models.URLField(max_length=500)),
+                ("machine_id", models.CharField(max_length=255)),
+                ("encrypted_password", models.TextField()),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={"ordering": ("-updated_at",)},
+        ),
+    ]

crowdsec_integration/migrations/__init__.py

@@ -0,0 +1 @@
+

crowdsec_integration/models.py

@@ -0,0 +1,14 @@
+from django.db import models
+
+
+class CrowdSecConnection(models.Model):
+    """CrowdSec LAPI credentials for the local Log Collector entity."""
+
+    entity_id = models.PositiveBigIntegerField(unique=True, db_index=True)
+    api_url = models.URLField(max_length=500)
+    machine_id = models.CharField(max_length=255)
+    encrypted_password = models.TextField()
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ("-updated_at",)

crowdsec_integration/services.py

@@ -0,0 +1,70 @@
+import base64
+import hashlib
+from urllib.parse import urlsplit
+
+import requests
+from cryptography.fernet import Fernet, InvalidToken
+from django.conf import settings
+
+from .models import CrowdSecConnection
+
+
+class CrowdSecError(Exception):
+    pass
+
+
+def _fernet():
+    key = base64.urlsafe_b64encode(hashlib.sha256(settings.SECRET_KEY.encode()).digest())
+    return Fernet(key)
+
+
+def encrypt_password(password):
+    return _fernet().encrypt(password.encode()).decode()
+
+
+def _password(connection):
+    try:
+        return _fernet().decrypt(connection.encrypted_password.encode()).decode()
+    except (InvalidToken, ValueError) as exc:
+        raise CrowdSecError("Saved credential cannot be decrypted. Re-enter the CrowdSec credential.") from exc
+
+
+def _url(api_url, path):
+    parsed = urlsplit(api_url)
+    if parsed.scheme not in {"https", "http"} or not parsed.hostname or parsed.username or parsed.password:
+        raise CrowdSecError("Enter a valid CrowdSec Local API URL.")
+    if parsed.scheme != "https" and parsed.hostname not in {"localhost", "127.0.0.1", "::1"}:
+        raise CrowdSecError("CrowdSec connections must use HTTPS except for loopback development.")
+    return f"{api_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def request(connection, method, path, **kwargs):
+    try:
+        login = requests.post(
+            _url(connection.api_url, "v1/watchers/login"),
+            json={"machine_id": connection.machine_id, "password": _password(connection)},
+            timeout=8,
+        )
+        login.raise_for_status()
+        token = login.json().get("token")
+        if not token:
+            raise CrowdSecError("CrowdSec returned no session token.")
+        response = requests.request(
+            method, _url(connection.api_url, path),
+            headers={"Authorization": f"Bearer {token}"}, timeout=8, **kwargs,
+        )
+        response.raise_for_status()
+        return response.json() if response.content else {}
+    except CrowdSecError:
+        raise
+    except (requests.RequestException, ValueError) as exc:
+        raise CrowdSecError("CrowdSec connection failed. Check the URL, credentials, and LAPI permissions.") from exc
+
+
+def validate_connection(api_url, machine_id, password):
+    class Candidate:
+        pass
+    candidate = Candidate()
+    candidate.api_url, candidate.machine_id = api_url, machine_id
+    candidate.encrypted_password = encrypt_password(password)
+    request(candidate, "GET", "v1/alerts?limit=1")

log_collector/__init__.py

@@ -0,0 +1 @@
+

log_collector/apps.py

@@ -0,0 +1,13 @@
+from django.apps import AppConfig
+
+
+class LogCollectorConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "log_collector"
+
+    def ready(self):
+        from django.core.checks import register
+
+        from log_collector.services.client_ip import check_security_cidrs
+
+        register(check_security_cidrs)

log_collector/consumers.py

@@ -0,0 +1,56 @@
+"""Authenticated, read-only security incident and block notifications."""
+
+import json
+from urllib.parse import parse_qsl
+
+from channels.db import database_sync_to_async
+from channels.generic.websocket import AsyncWebsocketConsumer
+
+from log_collector.models import LogCollectorEntity
+from log_collector.security_events import sanitize_security_event, security_group_name
+
+
+class SecurityEventsConsumer(AsyncWebsocketConsumer):
+    async def connect(self):
+        self.security_group = None
+        user = self.scope.get("user")
+        credentials = {"token", "api_key", "api_token", "access_token", "authorization", "key"}
+        query = self.scope.get("query_string", b"").decode("utf-8", errors="replace")
+        if (not user or not user.is_authenticated or not user.is_active
+                or any(key.lower() in credentials for key, _ in parse_qsl(query, keep_blank_values=True))):
+            await self.close(code=4401)
+            return
+        if not await self.is_data_center_member(user):
+            await self.close(code=4403)
+            return
+        self.entity_id = await self.active_entity_id(self.scope["url_route"]["kwargs"]["slug"])
+        if self.entity_id is None:
+            await self.close(code=4404)
+            return
+        self.security_group = security_group_name(self.entity_id)
+        await self.channel_layer.group_add(self.security_group, self.channel_name)
+        await self.accept()
+
+    @database_sync_to_async
+    def is_data_center_member(self, user):
+        return user.groups.filter(name="DATA_CENTER").exists()
+
+    @database_sync_to_async
+    def active_entity_id(self, slug):
+        return LogCollectorEntity.objects.filter(slug=slug, is_active=True).values_list("pk", flat=True).first()
+
+    async def disconnect(self, close_code):
+        if self.security_group:
+            await self.channel_layer.group_discard(self.security_group, self.channel_name)
+
+    async def receive(self, text_data=None, bytes_data=None):
+        # No client protocol: text, JSON actions and binary input have no effects.
+        pass
+
+    async def security_event(self, message):
+        payload = message.get("event", {})
+        if payload.get("entity_id") != self.entity_id:
+            return
+        event = sanitize_security_event(self.entity_id, payload.get("type"), payload)
+        if event is not None:
+            await self.send(text_data=json.dumps(event))

log_collector/docs/api.md

@@ -0,0 +1,27 @@
+# API integration
+
+Mounting `log_collector.urls` at `/log-collector/` exposes read-only entity
+resources under `/log-collector/api/entities/<slug>/`. Resources include
+`metrics/`, `access-logs/`, `geolocation/`, `user-sessions/`, `endpoints/`, and
+`audit-events/`, subject to the entity's feature flags and caller permissions.
+Table resources support pagination; supported resources accept `export=csv`.
+
+Generate an entity-scoped collector token as a superuser on the entity Manage
+page. The raw token is shown once. Server-to-server callers send it in the
+`X-Api-Key` header. The server stores a hash, not the raw token. Tokens may
+have expiry, caller IP/CIDR, and origin restrictions. Do not embed a collector
+token in browser or mobile application code.
+
+To view another installation, create an integration entity with its HTTPS base
+URL, remote entity slug, and remote collector token. Remote calls are read-only
+and fetched on demand; they do not copy remote raw logs into the local database.
+The remote service must expose the LOG Collector API. Arbitrary logging APIs
+need a separate adapter.
+
+The available entity routes also include `security-summary/`,
+`security-incidents/`, `security-blocks/`, and CrowdSec status and decisions.
+State-changing security endpoints require an authorized same-origin session,
+CSRF protection, and the required operator role; a read-only API token cannot
+perform those actions. An expired, revoked, mismatched, or caller-restricted
+token is denied. Inspect recent token usage on the entity Manage page to
+diagnose denials without logging the raw key.

log_collector/docs/configuration.md

@@ -0,0 +1,82 @@
+# Configuration
+
+## Nginx collection
+
+Set `LOG_COLLECTOR_NGINX_ACCESS_LOG_PATHS` to the Nginx access-log files that
+the Django and worker processes can read. The default path is
+`/var/log/nginx/access.log`; set `[]` when no local file is available. The
+reader accepts Nginx common and combined access-log entries. Configure the
+hosting entity's paths, cooldown, maximum lines per sync, and retention on its
+Manage page. Access-log rotation must leave new files readable by workers.
+
+## ASGI and WebSockets
+
+Set `ASGI_APPLICATION` and a production `CHANNEL_LAYERS` backend, such as
+`channels_redis`, in the host project. Include the collector route under the
+host's authenticated ASGI WebSocket application:
+
+```python
+from channels.auth import AuthMiddlewareStack
+from channels.routing import ProtocolTypeRouter, URLRouter
+from django.core.asgi import get_asgi_application
+
+django_asgi_app = get_asgi_application()
+from log_collector.routing import websocket_urlpatterns
+
+application = ProtocolTypeRouter({
+    "http": django_asgi_app,
+    "websocket": AuthMiddlewareStack(URLRouter(websocket_urlpatterns)),
+})
+```
+
+The route is `/ws/log-collector/entities/<slug>/security/`. Its origin
+validator is part of the route. Set the host's `ALLOWED_HOSTS` correctly.
+The browser Origin must match the WebSocket Host and port; when
+`LOG_COLLECTOR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS` is set, that exact origin
+must also appear in the list.
+
+## Celery
+
+Configure a Celery broker, worker, and beat scheduler in the host project.
+The default queue handles `log_collector.tasks.collect_analyze_and_respond`,
+`expire_security_blocks`, and `retry_security_edge_actions`. Schedule the
+first task at the desired polling interval (five seconds in the original
+deployment) and the latter two at one-minute intervals. An `sms` queue worker
+is required when security SMS is enabled; route `queue_security_incident_sms_alert`,
+`send_security_incident_sms_chunk`, and `retry_security_incident_sms_alert` there.
+Collection can also run on dashboard/API requests, but continuous collection
+requires beat and a worker.
+
+## Optional host integrations
+
+The local geolocation and user-session APIs need models supplied by the host:
+
+```python
+LOG_COLLECTOR_GEOLOCATION_MODEL = "your_geo_app.UserLocation"
+LOG_COLLECTOR_USER_SESSION_MODEL = "your_sessions_app.UserSession"
+```
+
+The geolocation model must expose `user`, `captured_at`, `ip_address`,
+`latitude`, `longitude`, `country`, and `city`; the session model must expose
+`user`, `session_key`, `ip`, `created_at`, `last_seen_at`, and `user_agent`.
+Disable the entity's geolocation or user-session feature when no compatible
+model exists. With an enabled feature but no model configured, its local API
+returns HTTP 503 naming the missing setting; security summaries still work
+without session data. Remote entities use the remote collector API instead.
+
+
+The package does not assume a particular user-profile or SMS provider. Set
+the following to importable dotted Python callables when using those actions:
+
+- `LOG_COLLECTOR_ACCOUNT_CONTAINMENT_FUNCTION`: accepts a user and returns an
+  object with `as_dict()` describing revoked authentication state.
+- `LOG_COLLECTOR_SMS_RECIPIENTS_FUNCTION`: returns iterable
+  `SecuritySMSRecipient(user, phone_number)` values from
+  `log_collector.integrations`.
+- `LOG_COLLECTOR_SMS_SENDER_FUNCTION`: accepts `mobile_number`, `message`, and
+  `context` keyword arguments.
+
+`LOG_COLLECTOR_SECURITY_SMS_ENABLED` defaults to false. Enable it only after
+the recipient and sender functions, provider, and `sms` worker are configured.
+The optional Nginx edge-block helper is supplied and reviewed by the host;
+the wheel does not install privileged executables. See [Operations](operations-guide.md).

log_collector/docs/installation.md

@@ -0,0 +1,40 @@
+# Installation
+
+LOG Collector supports Python 3.12–3.13 and Django 6.0.x. Use a virtual
+environment in the host Django project:
+
+```shell
+python -m pip install 'codefilterph-logcollector[redis,asgi]'
+```
+
+Add the apps and mount the HTTP URLs:
+
+```python
+INSTALLED_APPS += [
+    "channels",
+    "rest_framework",
+    "crowdsec_integration.apps.CrowdSecIntegrationConfig",
+    "log_collector.apps.LogCollectorConfig",
+]
+
+# In the project's urls.py:
+urlpatterns += [path("log-collector/", include("log_collector.urls"))]
+```
+
+Keep Django's `auth`, `contenttypes`, and `sessions` apps installed. Apply the
+database schema with `python manage.py migrate`. The collector uses
+`AUTH_USER_MODEL`, so configure a custom user model before its first migration
+if your project needs one.
+
+Add `log_collector.middleware.SecurityIPBlockMiddleware` after Django's
+`AuthenticationMiddleware` if application-level IP blocking is wanted. Give
+authorized dashboard users membership in the `DATA_CENTER` group. A user also
+needs `is_superuser=True` to open the Manage page or change configuration.
+
+The default hosting entity is created on first access and has slug
+`hosting-app`. Open `/log-collector/entities/hosting-app/manage/` as a
+superuser to set the displayed app name, shared theme, and local collection
+paths. An unset name displays **LOG Collector**.
+
+See [Configuration](configuration.md) before enabling collection, WebSockets,
+Celery, SMS, or Nginx edge blocking.

log_collector/docs/operations-guide.md

@@ -0,0 +1,52 @@
+# Operations
+
+After installation, run `python manage.py check` and `python manage.py migrate`
+with the host's settings. Confirm the web and Celery worker accounts can read
+each configured Nginx log. Mount log files read-only where possible; grant the
+smallest filesystem permission needed. Check the collector's Manage page for
+local connection health and recent token usage.
+
+Run an ASGI server and a channel layer for live security updates. Run Celery
+beat and workers consuming `default`; add a worker consuming `sms` when SMS
+alerts are enabled. A disconnected WebSocket does not stop HTTP refresh or
+scheduled collection. Retain monitoring for worker failures, log rotation,
+unreadable paths, and stale last-sync timestamps.
+
+Application-level IP blocking is supplied by the optional collector middleware.
+Edge blocking needs a separately installed and reviewed fixed-path helper in
+`LOG_COLLECTOR_NGINX_BLOCK_HELPER`. Never configure a shell command or grant
+the web account broad Nginx privileges. The helper must validate its inputs
+and verify the resulting Nginx rule before reporting success.
+
+Before upgrading, back up the database and apply the package migrations on a
+staging copy. Keep the same Django app labels and migration names. Roll out
+the new package version to web and worker processes together, then verify
+collection, API reads, WebSocket connection, and queued tasks. Rotate API
+tokens and SMS provider credentials through the host's normal secret process;
+do not put secrets in package configuration files.
+
+## Publishing a release
+
+Publish from the standalone `codefilterPH/logcollector` repository. Review its
+source and archives for host-specific names, paths, credentials, and unrelated
+apps. Confirm the public license and increment the version in `pyproject.toml`.
+Check that the normalized `codefilterph-logcollector` name is still available on both
+package indexes immediately before the first release.
+
+In TestPyPI, register a Trusted Publisher for GitHub owner `codefilterPH`,
+repository `logcollector`, workflow `publish.yml`, and environment `testpypi`.
+Protect that GitHub environment. Tag the reviewed version as `vX.Y.Z`, then
+run **Publish package** against that tag with target `testpypi`. Check the
+uploaded files and README. In a fresh environment, install dependencies from
+PyPI, then install the exact candidate from TestPyPI with
+`python -m pip install --no-deps --index-url https://test.pypi.org/simple/ codefilterph-logcollector==X.Y.Z`.
+Run the installation and configuration checks on that candidate.
+
+For production, register a separate PyPI Trusted Publisher with the same
+owner, repository, and workflow but environment `pypi`. Require review for
+that GitHub environment. Run the same workflow against the reviewed tag with
+target `pypi`. The workflow uses short-lived OIDC credentials; no PyPI API
+token belongs in the repository. Verify `python -m pip install
+codefilterph-logcollector==X.Y.Z` in a fresh environment, inspect the installed guides,
+and record release notes. A package version cannot be overwritten on PyPI;
+fixes require a new version and tag.