~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""Security module for verified file write operations.
This module ensures that file writes only occur when explicitly allowed by configuration,
maintaining the encryption-at-rest security model.
"""
import json
import os
from pathlib import Path
from typing import Any
from loguru import logger
# Platforms without O_NOFOLLOW retain their normal symlink-following behavior.
_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
def _open_nofollow(path: str, flags: int) -> int:
"""Add supported leaf-symlink refusal to Python's normal open flags."""
return os.open(path, flags | _O_NOFOLLOW, 0o666)
def _open_nofollow_with_permissions(
path: str, flags: int, permissions: int
) -> int:
"""Tighten an existing file before truncation, or create it privately."""
truncate = bool(flags & os.O_TRUNC)
fd = os.open(path, (flags & ~os.O_TRUNC) | _O_NOFOLLOW, permissions)
try:
os.fchmod(fd, permissions)
if truncate:
os.ftruncate(fd, 0)
except BaseException:
os.close(fd)
raise
return fd
# Keys that should never be written to disk in clear text
SENSITIVE_KEYS = frozenset(
{
"password",
"api_key",
"apikey",
"api-key",
"secret",
"secret_key",
"secretkey",
"token",
"access_token",
"refresh_token",
"private_key",
"privatekey",
"credentials",
"auth",
"authorization",
}
)
def _sanitize_sensitive_data(data: Any) -> Any:
"""Remove sensitive keys from data before writing to disk.
Args:
data: Data to sanitize (dict, list, or primitive)
Returns:
Sanitized copy of the data with sensitive keys redacted
"""
if isinstance(data, dict):
result = {}
for key, value in data.items():
key_lower = key.lower() if isinstance(key, str) else key
if key_lower in SENSITIVE_KEYS:
result[key] = "[REDACTED]"
else:
result[key] = _sanitize_sensitive_data(value)
return result
if isinstance(data, list):
return [_sanitize_sensitive_data(item) for item in data]
return data
class FileWriteSecurityError(Exception):
"""Raised when a file write operation is not allowed by security settings."""
pass
def write_file_verified(
filepath: str | Path,
content: str,
setting_name: str,
required_value: Any = True,
context: str = "",
mode: str = "w",
encoding: str = "utf-8",
settings_snapshot: dict = None,
permissions: int | None = None,
) -> None:
"""Write content to a file only if security settings allow it.
Args:
filepath: Path to the file to write
content: Content to write to the file
setting_name: Configuration setting name to check (e.g., "api.allow_file_output")
required_value: Required value for the setting (default: True)
context: Description of what's being written (for error messages)
mode: File open mode (default: "w")
encoding: File encoding (default: "utf-8")
settings_snapshot: Optional settings snapshot for programmatic mode
permissions: POSIX file mode for private output. Existing files are
tightened before their contents are replaced.
Raises:
FileWriteSecurityError: If the security setting doesn't match required value
OSError: errno ELOOP, if the destination leaf is a symlink and the
platform exposes O_NOFOLLOW
Example:
>>> write_file_verified(
... "report.md",
... markdown_content,
... "api.allow_file_output",
... context="API research report"
... )
"""
from ..config.search_config import get_setting_from_snapshot
try:
actual_value = get_setting_from_snapshot(
setting_name, settings_snapshot=settings_snapshot
)
except Exception:
# Setting doesn't exist - default deny
actual_value = None
if actual_value != required_value:
error_msg = (
f"File write not allowed: {context or 'file operation'}. "
f"Set '{setting_name}={required_value}' in config to enable this feature."
)
logger.warning(error_msg)
raise FileWriteSecurityError(error_msg)
# Where O_NOFOLLOW is available, refuse a symlink at the final path
# component. Parent-directory symlinks and a leaf already dereferenced
# by the caller's Path.resolve() are outside this check.
# Let open() validate modes, own the descriptor and handle text/binary
# translation. This remains an in-place write, not an atomic replacement.
opener = _open_nofollow
if permissions is not None:
if os.name != "posix" or not 0 <= permissions <= 0o777:
raise ValueError("Private POSIX file permissions are unavailable")
def private_opener(path: str, flags: int) -> int:
return _open_nofollow_with_permissions(path, flags, permissions)
opener = private_opener
if "b" in mode:
with open(filepath, mode, opener=opener) as f: # nosec B603
f.write(content)
else:
with open(filepath, mode, encoding=encoding, opener=opener) as f: # nosec B603
f.write(content)
logger.debug(
f"Verified file write: {filepath} (setting: {setting_name}={required_value})"
)
def write_json_verified(
filepath: str | Path,
data: dict | list,
setting_name: str,
required_value: Any = True,
context: str = "",
settings_snapshot: dict = None,
permissions: int | None = None,
**json_kwargs,
) -> None:
"""Write JSON data to a file only if security settings allow it.
Args:
filepath: Path to the file to write
data: Dictionary or list to serialize as JSON
setting_name: Configuration setting name to check
required_value: Required value for the setting (default: True)
context: Description of what's being written (for error messages)
settings_snapshot: Optional settings snapshot for programmatic mode
permissions: POSIX file mode for private output.
**json_kwargs: Additional keyword arguments to pass to json.dumps()
(e.g., indent=2, ensure_ascii=False, sort_keys=True, default=custom_serializer)
Raises:
FileWriteSecurityError: If the security setting doesn't match required value
Example:
>>> write_json_verified(
... "results.json",
... {"accuracy": 0.95},
... "benchmark.allow_file_output",
... context="benchmark results",
... indent=2,
... sort_keys=True
... )
"""
# Default to indent=2 if not specified for readability
if "indent" not in json_kwargs:
json_kwargs["indent"] = 2
# Sanitize sensitive data before writing to disk
sanitized_data = _sanitize_sensitive_data(data)
content = json.dumps(sanitized_data, **json_kwargs)
write_file_verified(
filepath,
content,
setting_name,
required_value,
context,
mode="w",
encoding="utf-8",
settings_snapshot=settings_snapshot,
permissions=permissions,
)